Merge newer master into skill catalog hot refresh

packages/client/AGENTS.md

@@ -75,7 +75,7 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 Bringing up a new `packages/client/<name>` plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):
 
 1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./invariant`/`./client`/`./src/*`/`./package.json`, `dshClient` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency plus `support/invariants`), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])`), `src/index.ts` (empty node-half apply), `src/invariant.ts` (companion with a real reason), `src/css-modules.d.ts` when using CSS Modules, `README.md` with the Model Experience section.
-2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; the `CLIENT_PACKAGES` roster in `apps/cli/src/web.ts`; an `apps/cli/package.json` dependency (`mountWebPlugins` resolves roster packages against the composing app's URL — a roster row that is not a dependency of `apps/cli` fails to mount). `pnpm-workspace.yaml` already globs `packages/*/*`.
+2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `apps/cli/cordis.yml`; an `apps/cli/package.json` dependency (Loader resolves each config-tree package against the composing app's URL — a row whose package is not an `apps/cli` dependency fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
 3. **dshClient manifest semantics**: `platform: 'web'` always; `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is cordis fiber inject waiting on *services*, nothing else.
 4. **Registering into another package's slot**: if the declaring host provides no waitable service, your apply's order relative to the host's is unconstrained — a bare `slots.register` into its slot races boot (intermittent `slot "..." is not declared` page failures). Register with declaration-aware deferral: check `ctx.slots.spec(name)`, otherwise `ctx.slots.subscribe(name)` and register on the declaration event (SlotCore supports subscribing ahead of declaration); make the registration idempotent, and unsubscribe + dispose in the effect disposer. Only take a service edge in `inject` when the host actually provides one (ui-question → `'conversation'` is that case).
 5. Rebuild the bundle (`pnpm --filter <pkg> bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources.

packages/client/connection/src/client/api.ts

@@ -10,6 +10,8 @@ export type {
   ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, CommandExecuteResult, SkillsApi, SkillEntry,
+  ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  ModelReasoningEffort, ModelTarget, SessionModels,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 export type {

packages/client/connection/src/client/fixture.ts

@@ -9,7 +9,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId, TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
   ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
-  RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
+  ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
   ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -46,6 +46,25 @@ const MARKDOWN_FIXTURE = [
 
 const USER_MARKDOWN_LITERAL = '用户字面量：# 不渲染 `code` [link](https://example.com)'
 
+const DEEPSEEK_REASONING = {
+  efforts: [
+    { id: 'off', name: 'Off' },
+    { id: 'high', name: 'High' },
+    { id: 'max', name: 'Max' },
+  ],
+  defaultEffort: 'high',
+}
+
+const OPENAI_REASONING = {
+  efforts: [
+    { id: 'off', name: 'Off' },
+    { id: 'medium', name: 'Medium' },
+    { id: 'high', name: 'High' },
+    { id: 'max', name: 'Max' },
+  ],
+  defaultEffort: 'medium',
+}
+
 function sid(id: string): SessionId {
   return id as SessionId
 }
@@ -379,6 +398,10 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, blank: false, cwd: '/tmp/fixture' },
   ]
   const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
+  const modelTargets = new Map<SessionId, ModelTarget>(sessions.map(session => [
+    session.sessionId,
+    { provider: 'deepseek', model: 'deepseek-v4-flash' },
+  ]))
   const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 60]])
   let nextSession = 1
   let nextRpc = 1
@@ -621,6 +644,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
           sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: true, cwd,
         }
         sessions.push(created)
+        modelTargets.set(created.sessionId, { provider: 'deepseek', model: 'deepseek-v4-flash' })
         attachedSessions += 1
         const emitSession = (): void => {
           // Mirrors the host: the frame fires at creation, so blank is constantly true.
@@ -653,6 +677,47 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         if (doomed) throw new Error('fixture: simulated history transport failure')
         return ok(request, { ...page, ...todos === undefined ? {} : { todos } })
       },
+      models: request => ok(request, {
+        current: modelTargets.get(request.payload.sessionId)
+          ?? { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        groups: [
+          {
+            id: 'deepseek',
+            name: 'DeepSeek',
+            models: [
+              {
+                id: 'deepseek-v4-flash',
+                name: 'DeepSeek-V4-Flash',
+                description: '快速响应',
+                reasoning: DEEPSEEK_REASONING,
+              },
+              {
+                id: 'deepseek-v4-pro',
+                name: 'DeepSeek-V4-Pro',
+                description: '复杂任务',
+                reasoning: DEEPSEEK_REASONING,
+              },
+            ],
+          },
+          {
+            id: 'openai',
+            name: 'OpenAI',
+            models: [{ id: 'gpt-5', name: 'GPT-5', reasoning: OPENAI_REASONING }],
+          },
+        ],
+        failures: [],
+      }),
+      selectModel: (request) => {
+        const selected: ModelTarget = {
+          provider: request.payload.provider,
+          model: request.payload.model,
+          ...request.payload.reasoningEffort === undefined
+            ? {}
+            : { reasoningEffort: request.payload.reasoningEffort },
+        }
+        modelTargets.set(request.payload.sessionId, selected)
+        return ok(request, { selected })
+      },
       prompt: (request) => {
         const { sessionId: id, mode, content } = request.payload
         const summary = summaryOf(id)
@@ -687,7 +752,13 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
           turn,
           userText === 'render markdown'
             ? MARKDOWN_FIXTURE
-            : `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`,
+            : userText === 'report model'
+              ? (() => {
+                const target = modelTargets.get(id)
+                return `当前模型：${target?.provider ?? 'unknown'}/${target?.model ?? 'unknown'}`
+                  + (target?.reasoningEffort === undefined ? '' : ` · 推理等级：${target.reasoningEffort}`)
+              })()
+              : `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`,
         )
         return ok(request, { accepted: true as const })
       },
@@ -950,6 +1021,8 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'session.list': return this.api.sessions.list(request)
       case 'session.create': return this.api.sessions.create(request)
       case 'session.history': return this.api.sessions.history(request)
+      case 'session.models': return this.api.sessions.models(request)
+      case 'session.selectModel': return this.api.sessions.selectModel(request)
       case 'session.prompt': return this.api.sessions.prompt(request)
       case 'session.cancel': return this.api.sessions.cancel(request)
       case 'host.describe': return this.api.host.describe(request)

packages/client/connection/src/client/index.ts

@@ -15,6 +15,8 @@ export type {
   ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, CommandExecuteResult, SkillsApi, SkillEntry,
+  ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  ModelReasoningEffort, ModelTarget, SessionModels,
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
   IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,

packages/client/connection/tests/fake-api.ts

@@ -2,8 +2,8 @@
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
-  CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, MuxFrame,
-  RpcRequest, RpcResponse, SessionId, SkillEntry,
+  CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  RpcRequest, RpcResponse, SessionId, SessionModels, SkillEntry,
 } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
 
@@ -45,9 +45,21 @@ export class FakeApiClient implements IApiClient {
   onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
-    () => Promise.resolve(ok({ events: [], hasMore: false }))
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelTarget: ModelTarget }>> =
+    () => Promise.resolve(ok({
+      events: [],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-chat' },
+    }))
 
+  onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
+    current: { provider: 'deepseek', model: 'deepseek-chat' },
+    groups: [],
+    failures: [],
+  }))
+  onSelectModel: (payload: ModelTarget & { sessionId: SessionId })
+  => Promise<RpcResponse<{ selected: ModelTarget }>> =
+    payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
@@ -66,6 +78,9 @@ export class FakeApiClient implements IApiClient {
     create: (payload: unknown) => this.record('session.create', payload, this.onCreate(payload)),
     history: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) =>
       this.record('session.history', payload, this.onHistory(payload)),
+    models: (payload: unknown) => this.record('session.models', payload, this.onModels(payload)),
+    selectModel: (payload: ModelTarget & { sessionId: SessionId }) =>
+      this.record('session.selectModel', payload, this.onSelectModel(payload)),
     prompt: (payload: unknown) => this.record('session.prompt', payload, this.onPrompt(payload)),
     cancel: (payload: unknown) => this.record('session.cancel', payload, this.onCancel(payload)),
   }
@@ -92,12 +107,10 @@ export class FakeApiClient implements IApiClient {
 
   // Payloads stay `unknown` (lint-lane note above); response rows are the real
   // wire shapes so cases can program catalogs and skill lists without casts.
-  onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>>
-    = () => Promise.resolve(ok({ commands: [] }))
-  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>>
-    = () => Promise.resolve(ok({ matched: false }))
-  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
-    = () => Promise.resolve(ok({ skills: [] }))
+  onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>> = () => Promise.resolve(ok({ commands: [] }))
+  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>> =
+    () => Promise.resolve(ok({ matched: false }))
+  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>> = () => Promise.resolve(ok({ skills: [] }))
 
   readonly commands: IApiClient['commands'] = {
     list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),

packages/client/connection/tests/fixture.spec.ts

@@ -68,7 +68,41 @@ describe('createFixtureApi', () => {
     // Unknown session: empty page, not an error (history of a bare id).
     const empty = await api.sessions.history(req({ sessionId: sid('no-such'), maxMessages: 10 }))
     if (!empty.result.ok) throw new Error('empty failed')
-    expect(empty.result.value).toEqual({ events: [], hasMore: false })
+    expect(empty.result.value).toEqual({
+      events: [],
+      hasMore: false,
+    })
+  })
+
+  it('serves grouped models and keeps a selected target for later history and fixture requests', async () => {
+    const api = createFixtureApi()
+    const sessionId = sid('fx-alpha')
+    const catalog = await api.sessions.models(req({ sessionId }))
+    if (!catalog.result.ok) throw new Error('models failed')
+    expect(catalog.result.value.groups.map(group => group.name)).toEqual(['DeepSeek', 'OpenAI'])
+    expect(catalog.result.value.groups[0]?.models.map(model => model.id))
+      .toEqual(['deepseek-v4-flash', 'deepseek-v4-pro'])
+
+    const selected = await api.sessions.selectModel(req({
+      sessionId,
+      provider: 'openai',
+      model: 'gpt-5',
+    }))
+    if (!selected.result.ok) throw new Error('selection failed')
+    expect(selected.result.value.selected).toEqual({ provider: 'openai', model: 'gpt-5' })
+    const history = await api.sessions.history(req({ sessionId }))
+    if (!history.result.ok) throw new Error('history failed')
+
+    const prompt = await api.sessions.prompt(req({
+      sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: 'report model' }],
+    }))
+    expect(prompt.result.ok).toBe(true)
+    await new Promise(resolve => setTimeout(resolve, 600))
+    const after = await api.sessions.history(req({ sessionId }))
+    if (!after.result.ok) throw new Error('history failed')
+    expect(JSON.stringify(after.result.value.events)).toContain('openai/gpt-5')
   })
 
   it('emits the todo/write snapshot at the real tool boundary: between tool/call and tool/result, timestamps monotonic', async () => {

packages/client/hmr/src/client/index.ts

@@ -5,7 +5,7 @@
  * `rebuilt` frame it re-fetches the entry's bundle and swaps the cordis
  * fiber in place. Every graph entry is a plugin bundle under the web2 model
  * — `immediately` rows differ only in stage-one prefetch (a boot
- * optimization), so all nine plugin packages share these reload semantics;
+ * optimization), so all rostered plugin packages share these reload semantics;
  * normal packages (react family, cordis, shell, pure libs) are not entries
  * and shell changes still mean a page reload. Cascade is zero-touch:
  * downstream fibers key their activation epoch on provider fiber uids

packages/client/runtime/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
-README.md: a434b2d5719de2f30a883ee6e0d26264b3c62f4e
-README.zh.md: a79fa99578e6bce4f0ff8e7c1f7538df8a436778
+README.md: 81261945cb2fd8b15f7c2f15cb1ae0b8e9928499
+README.zh.md: cbbf6eded4a5375223791275f26f3bc7b6553200

packages/client/runtime/README.md

@@ -24,13 +24,17 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 `SessionManager` retains the latest validated `session/title` control snapshot independently of list and session-instance arrival. Newer event seqs replace older snapshots, title timestamps contribute to list recency, and a subscription baseline discards any retained title beyond its `lastSeq` before the optional folded title arrives. Explicit session removal also clears the retained title. The client-facing `SessionSummary.title` is therefore only the actual durable title; `displayTitle` is always present and falls back through the cwd basename and session id. A cold persisted session keeps that fallback until opening or resuming it causes the host to fold and project its log-backed title.
 
+## Session model selection
+
+Each resident `Session` owns a `modelSelection` snapshot containing the current provider/model target, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current target, opening a selector refreshes the directory, and selection failures preserve the last target and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the target reported by the Host without replacing unchanged selection substructure.
+
 ## Model Experience
 
-None, as the client runtime hosts browser-side services and the session object layer; nothing here reaches a model request.
+None, as the session object layer selects the provider/model route used by a later Host request but adds no model-visible content.
 
 #### KV Cache effect
 
-None; this package neither assembles nor sends a provider request.
+Changing the target can change or invalidate provider-side cache reuse; this package does not alter the prompt prefix itself.
 
 ## Known Limitations and Deferred Work
 

packages/client/runtime/README.zh.md

@@ -24,13 +24,17 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `SessionManager` 独立于列表和 Session 实例到达情况，保留最近一次通过验证的 `session/title` 控制快照。seq 更新的事件会替换旧快照，标题时间戳计入列表新近程度；订阅基线会先丢弃 seq 超过其 `lastSeq` 的任何已保留标题，再接收可选的折叠标题。显式移除 Session 也会清除已保留标题。因此，面向客户端的 `SessionSummary.title` 只包含真实的持久标题；`displayTitle` 始终存在，并依次回退到 cwd basename 和 Session id。冷启动的持久会话会保持该回退值，直到打开或恢复会话，促使主机折叠并投影日志支持的标题。
 
+## 会话模型选择
+
+每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。
+
 ## 模型体验
 
-无。客户端运行时承载浏览器侧服务与 Session 对象层；这里没有任何内容进入模型请求。
+无，因为 Session 对象层会选择后续 Host 请求使用的提供方/模型路由，但不添加任何模型可见内容。
 
 #### KV Cache 影响
 
-无；该包既不组装也不发送提供方请求。
+更改目标可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
 
 ## 已知限制与暂缓事项
 

packages/client/runtime/tests/fake-api.ts

@@ -2,8 +2,8 @@
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
-  ClientResponse, CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, MuxFrame,
-  RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SkillEntry,
+  ClientResponse, CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionModels, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
@@ -61,10 +61,23 @@ export class FakeApiClient implements IApiClient {
   // Programmable slots (defaults answer OK-empty); reassign per case.
   onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
+  readonly defaultModel: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' }
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
   => Promise<RpcResponse<{ events: never[]; hasMore: boolean; todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[] }>> =
     () => Promise.resolve(ok({ events: [], hasMore: false }))
 
+  onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
+    current: this.defaultModel,
+    groups: [{
+      id: 'deepseek',
+      name: 'DeepSeek',
+      models: [{ id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash' }],
+    }],
+    failures: [],
+  }))
+  onSelectModel: (payload: { provider: string; model: string }) =>
+  Promise<RpcResponse<{ selected: ModelTarget }>> =
+    payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
@@ -83,6 +96,9 @@ export class FakeApiClient implements IApiClient {
     create: (payload: unknown) => this.record('session.create', payload, this.onCreate(payload)),
     history: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) =>
       this.record('session.history', payload, this.onHistory(payload)),
+    models: (payload: unknown) => this.record('session.models', payload, this.onModels(payload)),
+    selectModel: (payload: { provider: string; model: string }) =>
+      this.record('session.selectModel', payload, this.onSelectModel(payload)),
     prompt: (payload: unknown) => this.record('session.prompt', payload, this.onPrompt(payload)),
     cancel: (payload: unknown) => this.record('session.cancel', payload, this.onCancel(payload)),
   }
@@ -117,12 +133,10 @@ export class FakeApiClient implements IApiClient {
   // Payloads stay `unknown` (lint-lane note above); response rows are the real
   // wire shapes so cases can program requires-bearing catalogs and dual-address
   // skill lists without casts.
-  onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>>
-    = () => Promise.resolve(ok({ commands: [] }))
-  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>>
-    = () => Promise.resolve(ok({ matched: false }))
-  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
-    = () => Promise.resolve(ok({ skills: [] }))
+  onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>> = () => Promise.resolve(ok({ commands: [] }))
+  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>> =
+    () => Promise.resolve(ok({ matched: false }))
+  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>> = () => Promise.resolve(ok({ skills: [] }))
 
   readonly commands: IApiClient['commands'] = {
     list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),

packages/client/runtime/tests/manager.spec.ts

@@ -346,7 +346,11 @@ describe('remaining branches', () => {
 describe('connected generation', () => {
   it('refreshes the list and resyncs only opened instances', async () => {
     const api = new FakeApiClient()
-    api.onHistory = () => Promise.resolve(ok({ events: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    api.onHistory = () => Promise.resolve(ok({
+      events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-chat' },
+    }))
     const manager = new SessionManager(api)
     const openedSession = manager.get(S1)
     await openedSession.open()

packages/client/runtime/tests/session.spec.ts

@@ -75,7 +75,11 @@ describe('open', () => {
     const page = plainTurn(10, 0, '早', '安')
     session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: ev.turnStart(15, 1) })
     session.handleMuxEnvelope('r2' as never, { type: 'session/event', sessionId: SID, event: ev.user(16, '插进来的') })
-    gate.resolve(ok({ events: entries(page) as never[], hasMore: false }))
+    gate.resolve(ok({
+      events: entries(page) as never[],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    }))
     await opening
     const seqs = session.getSnapshot().nodes.map(n => n.seq)
     // Overlapping seq-15 frame (== page tail turn/end) was dropped; 16 appended once.
@@ -83,6 +87,7 @@ describe('open', () => {
   })
 })
 
+
 describe('live event path', () => {
   async function opened(events: SessionEvent[] = plainTurn(0, 0, 'a', 'b')) {
     const { api, session } = makeSession()
@@ -277,7 +282,11 @@ describe('paging', () => {
     api.onHistory = () => gate.promise
     const first = session.loadOlder()
     const second = session.loadOlder()
-    gate.resolve(ok({ events: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    gate.resolve(ok({
+      events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    }))
     await Promise.all([first, second])
     expect(api.callsOf('session.history')).toHaveLength(2) // open + one page, not two
   })
@@ -563,7 +572,11 @@ describe('remaining branches', () => {
     const opening = session.open()
     api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
     const resynced = session.resync()
-    stale.resolve(ok({ events: entries(plainTurn(0, 0, '旧', '代')) as never[], hasMore: false })) // success, but its generation is gone
+    stale.resolve(ok({
+      events: entries(plainTurn(0, 0, '旧', '代')) as never[],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'stale' },
+    })) // success, but its generation is gone
     await Promise.all([opening, resynced])
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9]) // only the fresh generation's window
   })
@@ -582,7 +595,11 @@ describe('remaining branches', () => {
     const opening = session.open() // triggers the second pull, which parks
     await vi.waitFor(() => { expect(call).toBe(2) })
     const resynced = session.resync()
-    secondPull.resolve(ok({ events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[], hasMore: false }))
+    secondPull.resolve(ok({
+      events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'stale' },
+    }))
     await Promise.all([opening, resynced])
     expect(session.getSnapshot().openState).toBe('open')
   })
@@ -596,7 +613,11 @@ describe('remaining branches', () => {
     session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(9, '洞') }) // starts repairGap
     api.onHistory = () => histResponse(plainTurn(6, 1, 'c', 'd'))
     const resynced = session.resync() // bumps the generation
-    repairPull.resolve(ok({ events: entries(plainTurn(0, 0, '旧', '页')) as never[], hasMore: false })) // repair result: stale, dropped
+    repairPull.resolve(ok({
+      events: entries(plainTurn(0, 0, '旧', '页')) as never[],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'stale' },
+    })) // repair result: stale, dropped
     await resynced
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
   })
@@ -640,6 +661,7 @@ describe('remaining branches', () => {
         { event: ev.toolResult(7, 1, 'h1', 'done'), view: { for: 'result', view: { card: 'generic', title: '历史果' } } },
       ] as never[],
       hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
     }))
     await session.open()
     expect(session.getSnapshot().nodes.at(-1)).toMatchObject({

packages/client/ui-conversation/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 32651291253077098bc43a930cf4ce11d29b1ed8
-README.zh.md: ea8f398541d7af6136b29c3365a78c4ea3a1e85d
+README.md: 56a445ccfa86e0b11cf5aefc37819a30746f0739
+README.zh.md: a7c160ecdd74074257c9d149630663dacd05c070

packages/client/ui-conversation/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, stats line, per-tool row slot with a bash sample registrant and the todo row), input dock (queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).
 
-The no-session hero renders the frontend Session Intent from the Session list projection, including its frontend Workspace Intent when no real Workspace exists. It declares `conversation.empty.workspace`, where ui-workspace registers the same picker used by the sidebar. WorkspacesService starts the cross-object flow; each Workspace or Session object owns its own materialization. The Session keeps its identity across publication and retains any prompt that still needs connection or delivery; ConversationRoot reads that `pendingPrompt` from `useSession` and edits or retries it through the scoped ConversationService.
+The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store.
 
 The view ring IS a slot: the conversation registration declares the `'conversation.view'` list slot (session scope) in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from the ring ledger's registration options (`id`/`order`/`label`). The chat view is this package's own ring entry; other plugins (ui-trajectory) contribute tabs through plain `ctx.slots.register` — the former package-local view registry (`registerView`/`ViewEntry`/`ConversationViewMap` and the chrome attachment table) is retired, with per-view chrome dissolved into the view components themselves.
 
@@ -14,7 +14,9 @@ Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.to
 
 The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the durable plan strip: it selects `todos` off the session snapshot and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and collapses to a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the persistent list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
 
-Per-session UI state (selection, ordinary composer draft, active view) lives in the declared chat store (`stores.ts` `createChatStore`): apply constructs one handle and passes it to the conversation, chat-view, and details registrations, so the session slots share one instance per session (selection written by the chat view, read by details) and the framework owns instance lifecycle and draft persistence. The frontend Session Intent comes from the Session list projection; after publication, any retained prompt comes from that Session's conversation snapshot. Components are pure — the framework standard kit (`useSession`/`sessionId` when session-scoped, plus global `useSessions`/`useWorkspaces`) and the store faces (`useStore`/`actions`) arrive automatically from the registration declaration; inject factories contribute plain data and callbacks for runtime Session actions, send/stop, tabs, details, and paging.
+Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks.
+
+The composer bar declares session-scoped single seats for `'conversation.input.plan'` and `'conversation.input.model'`, plus list slots for overlay, dock, left, and right input extensions. InputBar renders the model seat immediately before its pending indicator and send/stop button. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The resident no-session shell uses `DisabledInputBar` and therefore dispatches no session-scoped control seats.
 
 `src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations + composed slot props including the tool-row contract, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` (sample registrants) domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components (skeleton, chat rows) and the store factory stay internal and reach the page exclusively through apply's slot registrations (tests take them via the `./src/*` subpath).
 

packages/client/ui-conversation/README.zh.md

@@ -4,7 +4,7 @@
 
 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、统计行、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、输入区 dock（队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
 
-无会话主视觉区会渲染来自 Session 列表投影的前端 Session Intent；没有真实 Workspace 时，还会包含其前端 Workspace Intent。它声明 `conversation.empty.workspace`，ui-workspace 会在此注册侧边栏所用的同一选择器。WorkspacesService 启动跨对象流程；每个 Workspace 或 Session 对象拥有自身的物化。Session 在发布期间保持身份，并保留任何仍需连接或交付的提示词；ConversationRoot 读取该 `pendingPrompt`，其来源是 `useSession`，再通过 scope 内的 ConversationService 编辑或重试。
+常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。
 
 视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。
 
@@ -14,7 +14,9 @@
 
 todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: -1` 占用 `'conversation.input.dock'` 列表 slot（位于队列行之上），是常驻的计划条：它从会话快照中选取 `todos` 并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏，折叠时收成标题加 `"<已完成>/<总数> tasks · <n> in progress"` 的表头（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；常驻列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
 
-逐 Session UI 状态（选择、普通编辑器草稿、活跃视图）位于已声明的聊天 store（`stores.ts` `createChatStore`）中：apply 构造一个 handle，并将其传给会话、聊天视图和详情注册，因此 Session slot 每个 Session 共享一个实例（选择由聊天视图写入、详情读取），框架拥有实例生命周期与草稿持久化。前端 Session Intent 来自 Session 列表投影；发布后，任何保留的提示词都来自该 Session 的会话快照。组件保持纯粹：框架标准工具包（Session scope 下的 `useSession`／`sessionId`，以及全局 `useSessions`／`useWorkspaces`）和 store 表层（`useStore`／`actions`）会从注册声明自动到达；inject factory 为运行时 Session 操作、发送／停止、标签页、详情和分页贡献普通数据与回调。
+逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
+
+输入栏为 `'conversation.input.plan'` 和 `'conversation.input.model'` 声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。InputBar 将模型 seat 渲染在 pending 指示器与发送／停止按钮之前。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。常驻无会话壳使用 `DisabledInputBar`，因此不会分发任何会话作用域的控件 seat。
 
 `src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。
 

packages/client/ui-model/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/client/ui-model/README.md
+README.md: 267717c78434f7a73b1c1eebca0cc0f9d65c3642
+README.zh.md: 325b1d93d99ed22e0945c26f5a3a9e5b3b209c85

packages/client/ui-model/README.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-ui-model
+
+English | [中文](README.zh.md)
+
+Model selection plugin, browser half: TWO entries over ONE per-session directory owned by `ModelService` (`ctx.models`). The `/model` popupSelect contribution (registered through `ctx.command`) and the composer's named `conversation.input.model` seat both load the session's advisory directory through `session.models` and submit through `session.selectModel` via the same `ModelDirectory` instance. The compact composer trigger opens a two-level Model/Effort menu: models stay provider-grouped, while the selected exact model supplies its adapter-owned effort names, descriptions, and default. The Host-reported provider/model/reasoning target is the single fact both entries echo; `/model` applies the selected model's default effort, and the composer can then choose any advertised effort. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored target before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior target and directory. Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope.
+
+The `/client` export surface is the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state shape, and the seat's injected face type.
+
+## Model Experience
+
+Indirectly, through the `session.selectModel` RPC both entries submit: the Host snapshots the selected provider/model/reasoning target at the next prompt-assembly boundary, so the following request uses the chosen route and effort while a running step keeps its assembled target. The selection becomes durable only when the existing request header records a request that consumes it; menu interaction adds no prompt content.
+
+#### KV Cache effect
+
+Switching the route can reduce or invalidate provider-side cache reuse for subsequent requests; the prompt prefix itself is untouched.
+
+## Known Limitations and Deferred Work
+
+- **No create-time selection** — both entries address an existing session's agent; there is no draft-phase model choice to fold into session creation (the seed order at the host's `targetFor` documents where such a tier would go).
+- **Directory names are presentation-only** — selection and persistence use provider/model/effort ids; a provider whose catalog or exact-model metadata lookup fails lists as an unselectable failure row until reload.
+- **No arbitrary effort input** — the composer offers only the exact model's adapter-advertised levels; an adapter without reasoning metadata leaves the Effort row absent.

packages/client/ui-model/README.zh.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-ui-model
+
+[English](README.md) | 中文
+
+模型选择插件（浏览器半侧）：**两个入口共用一份 per-session 目录**，由 `ModelService`（`ctx.models`）持有。`/model` popupSelect contribution（经 `ctx.command` 注册）与 composer 的具名 `conversation.input.model` 坑位都通过同一个 `ModelDirectory` 实例，经 `session.models` 加载会话的建议目录，并经 `session.selectModel` 提交。紧凑型 composer 触发器会打开两级 Model/Effort 菜单：模型仍按提供方分组，所选确切模型则提供由其适配器持有的推理强度名称、说明和默认值。Host 报告的提供方／模型／推理（reasoning）目标是两个入口共同回显的唯一事实；`/model` 应用所选模型的默认推理强度，composer 随后可以选择任一已公布的推理强度。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。逐提供方元数据失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话 scope 一并释放。
+
+`/client` 导出面为插件本体（`apply`/`inject`）、`ModelService`、`ModelDirectory` 及其状态形状、坑位注入面类型。
+
+## Model Experience
+
+间接影响，经两个入口共同提交的 `session.selectModel` RPC：Host 在下一次提示词组装边界快照所选提供方／模型／推理强度目标，因此后续请求采用所选路由和推理强度，而运行中的步骤保留已组装目标。只有当现有请求头记录一次实际采用该选择的请求后，选择才会持久化；菜单交互不会添加提示词内容。
+
+#### KV Cache effect
+
+切换路由可能降低或作废提供方侧后续请求的缓存复用；提示词前缀本身不受影响。
+
+## Known Limitations and Deferred Work
+
+- **无创建期选择**——两个入口都寻址既有会话的 agent；没有 Draft 期模型选择折入会话创建的通道（host `targetFor` 处的种子序注释记录了该层未来的落点）。
+- **目录名仅供呈现**——选择与持久化使用提供方／模型／推理强度 id；目录查询或确切模型元数据查询失败的提供方以不可选失败行列出，重新加载前保持原样。
+- **不能任意输入推理强度**——composer 仅提供确切模型由适配器公布的推理强度；适配器没有推理元数据时不显示 Effort 行。

packages/client/ui-model/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-model",
+  "description": "Model selection: the /model popupSelect over session.models / session.selectModel",
+  "version": "0.0.1",
+  "private": true,
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-command"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-command": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "clsx": "^2.1.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-command": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "clsx": "^2.1.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/ui-model/src/client/ModelSelect.module.css

@@ -0,0 +1,251 @@
+.root {
+  position: relative;
+  min-width: 0;
+}
+
+/* Figma 313:14108 ToggleButton: 13/20 medium secondary label, 4px gap,
+   12px caption chevron; 28px chip height matches the sibling Plan /
+   Read-only selects in the same tool row. */
+.trigger {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  max-width: 220px;
+  height: 28px;
+  padding: 0 4px 0 8px;
+  border: none;
+  border-radius: 8px;
+  outline: none;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.trigger:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.trigger:focus-visible {
+  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);
+}
+
+.trigger:disabled {
+  color: var(--dsw-alias-label-dimmed);
+  cursor: default;
+}
+
+.triggerLabel {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Effort value beside the model name (mock's 'High': same 13/20/500, caption tone). */
+.triggerEffort {
+  flex: 0 0 auto;
+  color: var(--dsw-alias-label-caption);
+}
+
+.chevron {
+  flex: 0 0 auto;
+  color: var(--dsw-alias-label-caption);
+  transition: transform 120ms ease;
+}
+
+.chevronOpen {
+  transform: rotate(180deg);
+}
+
+.menu {
+  position: absolute;
+  right: 0;
+  bottom: calc(100% + 8px);
+  z-index: 20;
+  display: flex;
+  flex-direction: column;
+  width: min(240px, calc(100vw - 32px));
+  max-height: min(360px, calc(100vh - 96px));
+  overflow: hidden;
+  padding: 4px;
+  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border-radius: 12px;
+  background: var(--dsw-specific-input-major);
+  box-shadow: var(--dsw-shadow-lv3);
+  color: var(--dsw-alias-label-primary);
+}
+
+.status,
+.empty {
+  padding: 10px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+}
+
+.error,
+.warning {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 4px;
+  padding: 7px 8px;
+  border-radius: 8px;
+  background: var(--dsw-alias-interactive-bg-hover-danger);
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.warning {
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-state-warn-label);
+}
+
+.retry {
+  flex: 0 0 auto;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.groups {
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.group + .group {
+  margin-top: 4px;
+}
+
+.groupTitle {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  padding: 5px 8px 3px;
+  background: var(--dsw-specific-input-major);
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+  font-weight: 500;
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  min-height: 38px;
+  padding: 6px 8px;
+  border: none;
+  border-radius: 10px;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.option:hover:not(:disabled),
+.option:focus-visible,
+.selected {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.option:disabled {
+  color: var(--dsw-alias-label-dimmed);
+  cursor: default;
+}
+
+.optionCopy {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.modelName {
+  overflow: hidden;
+  color: inherit;
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 500;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.description,
+.unlisted {
+  overflow: hidden;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.unlisted {
+  color: var(--dsw-alias-state-warn-label);
+}
+
+.check {
+  display: grid;
+  place-items: center;
+  flex: 0 0 18px;
+  color: var(--dsw-alias-state-business-primary);
+}
+
+/* Two-level root cells (figma 496:26454 .Menu_cell): 40px row, 10px side
+   padding, 8px gap, 10px radius; 14/22 label in primary, value in the
+   #81858C tertiary tone, right chevron drilling into the sub-list. */
+.cell {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  height: 40px;
+  padding: 0 10px;
+  border: none;
+  border-radius: 10px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  line-height: 22px;
+  cursor: pointer;
+  text-align: left;
+}
+
+.cell:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.cellLabel {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cellValue {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.cellChevron {
+  flex: 0 0 auto;
+  color: var(--dsw-alias-label-tertiary);
+}

packages/client/ui-model/src/client/ModelSelect.tsx

@@ -0,0 +1,327 @@
+/**
+ * ModelSelect: the composer's named model seat (`conversation.input.model`).
+ * Two-level selection per figma 496:26454's MenuDropdown: the root menu is
+ * the Model / Effort row pair (label + current value + a right chevron),
+ * each drilling into its own list — the provider-grouped model list over
+ * the shared directory, and the effort levels. The trigger (313:14108's
+ * ToggleButton) shows both: model name + effort in the caption tone.
+ * Data and submission ride the SAME per-session ModelDirectory as the
+ * /model popup; exact-model reasoning metadata and the selected effort come
+ * from the Host rather than a client-owned vocabulary.
+ */
+import {
+  useEffect, useId, useMemo, useRef, useState, useSyncExternalStore,
+  type KeyboardEvent, type FocusEvent,
+} from 'react'
+import clsx from 'clsx'
+import type { ModelReasoningEffort, ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import {
+  IconCheckOutline16, IconChevronDownOutline14, IconChevronRightOutline14,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ModelSelectInjected } from './slots.ts'
+import css from './ModelSelect.module.css'
+
+/** Which pane the dropdown shows: the two-row root or one drilled-in list. */
+type Pane = 'root' | 'model' | 'effort'
+
+/** One dynamic effort row; undefined means preserve the provider default. */
+interface EffortChoice {
+  key: string
+  effort: string | undefined
+  label: string
+  description?: string
+}
+
+/**
+ * Render the composer model seat.
+ * @param props - owner share (locked) + injected face (shared directory store/verbs).
+ * @returns the trigger and, while open, the two-level menu.
+ */
+export function ModelSelect({ locked, directory, load, select }: ModelSelectInjected & { locked: boolean }) {
+  const state = useSyncExternalStore(
+    fn => directory.subscribe(fn),
+    () => directory.getSnapshot(),
+  )
+  const [open, setOpen] = useState(false)
+  const [pane, setPane] = useState<Pane>('root')
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const itemRefs = useRef<(HTMLButtonElement | null)[]>([])
+  const id = useId()
+
+  const choices = useMemo(() => state.groups.flatMap(group =>
+    group.models.map(model => ({
+      group,
+      model,
+      target: {
+        provider: group.id,
+        model: model.id,
+        ...model.reasoning?.defaultEffort === undefined
+          ? {}
+          : { reasoningEffort: model.reasoning.defaultEffort },
+      } satisfies ModelTarget,
+    }))), [state.groups])
+  const selectedIndex = state.current === null
+    ? -1
+    : choices.findIndex(c => c.target.provider === state.current?.provider && c.target.model === state.current.model)
+  const currentChoice = choices[selectedIndex]
+  const reasoning = currentChoice?.model.reasoning
+  const effectiveEffort = state.current?.reasoningEffort ?? reasoning?.defaultEffort
+  const effortLabel = reasoning === undefined
+    ? undefined
+    : effectiveEffort === undefined
+      ? 'Provider default'
+      : reasoning.efforts.find(level => level.id === effectiveEffort)?.name ?? effectiveEffort
+  const effortChoices = useMemo<readonly EffortChoice[]>(() => reasoning === undefined
+    ? []
+    : [
+      ...reasoning.defaultEffort === undefined
+        ? [{ key: 'provider-default', effort: undefined, label: 'Provider default' }]
+        : [],
+      ...reasoning.efforts.map((effort: ModelReasoningEffort) => ({
+        key: `effort:${effort.id}`,
+        effort: effort.id,
+        label: effort.name,
+        ...effort.description === undefined ? {} : { description: effort.description },
+      })),
+    ], [reasoning])
+  const busy = state.status === 'selecting'
+
+  // Mount-time load resolves the trigger label; every open refreshes.
+  useEffect(() => { load() }, [load])
+
+  useEffect(() => {
+    if (!open) return
+    const closeOutside = (event: MouseEvent): void => {
+      if (!rootRef.current?.contains(event.target as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', closeOutside)
+    return () => { document.removeEventListener('mousedown', closeOutside) }
+  }, [open])
+
+  const show = (): void => {
+    setPane('root')
+    setOpen(true)
+    load()
+  }
+
+  const close = (restoreFocus = false): void => {
+    setOpen(false)
+    setPane('root')
+    if (restoreFocus) queueMicrotask(() => { triggerRef.current?.focus() })
+  }
+
+  const moveFocus = (offset: number): void => {
+    const items = itemRefs.current.filter(item => item !== null)
+    if (items.length === 0) return
+    const active = items.findIndex(item => item === document.activeElement)
+    const next = (Math.max(active, 0) + offset + items.length) % items.length
+    items[next]?.focus()
+  }
+
+  const onRootKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
+    if (event.key === 'Escape' && open) {
+      event.preventDefault()
+      // Escape backs out of a drilled pane first, then closes.
+      if (pane !== 'root') setPane('root')
+      else close(true)
+      return
+    }
+    if (!open) return
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      moveFocus(event.key === 'ArrowDown' ? 1 : -1)
+    }
+  }
+
+  const onBlur = (event: FocusEvent<HTMLDivElement>): void => {
+    if (event.relatedTarget instanceof Node && rootRef.current?.contains(event.relatedTarget)) return
+    close()
+  }
+
+  const choose = (target: ModelTarget): void => {
+    if (state.current?.provider === target.provider && state.current.model === target.model) {
+      close(true)
+      return
+    }
+    void select(target).then((accepted) => {
+      if (accepted && rootRef.current !== null) close(true)
+    })
+  }
+
+  const chooseEffort = (effort: string | undefined): void => {
+    if (state.current === null) return
+    if (effectiveEffort === effort) {
+      close(true)
+      return
+    }
+    const target: ModelTarget = {
+      provider: state.current.provider,
+      model: state.current.model,
+      ...effort === undefined ? {} : { reasoningEffort: effort },
+    }
+    void select(target).then((accepted) => {
+      if (accepted && rootRef.current !== null) close(true)
+    })
+  }
+
+  const modelLabel = choices[selectedIndex]?.model.name ?? state.current?.model ?? '选择模型'
+  const triggerLabel = effortLabel === undefined ? modelLabel : `${modelLabel} · ${effortLabel}`
+  itemRefs.current = []
+  let itemIndex = 0
+  const itemRef = () => {
+    const at = itemIndex++
+    return (node: HTMLButtonElement | null) => { itemRefs.current[at] = node }
+  }
+
+  return (
+    <div ref={rootRef} className={css.root} onKeyDown={onRootKeyDown} onBlur={onBlur}>
+      <button
+        ref={triggerRef}
+        type="button"
+        className={css.trigger}
+        aria-label={`选择模型，当前 ${modelLabel}${effortLabel === undefined ? '' : `，推理等级 ${effortLabel}`}`}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? `${id}-menu` : undefined}
+        title={triggerLabel}
+        disabled={locked}
+        onClick={() => {
+          if (open) {
+            close()
+          } else {
+            show()
+          }
+        }}
+      >
+        <span className={css.triggerLabel}>{modelLabel}</span>
+        {effortLabel !== undefined && <span className={css.triggerEffort}>{effortLabel}</span>}
+        <IconChevronDownOutline14 className={clsx(css.chevron, open && css.chevronOpen)} />
+      </button>
+
+      {open && (
+        <div
+          id={`${id}-menu`}
+          className={css.menu}
+          role="menu"
+          aria-label="模型与推理等级"
+          aria-busy={state.status === 'loading' || busy}
+        >
+          {pane === 'root' && (
+            <>
+              <button ref={itemRef()} type="button" role="menuitem" className={css.cell} onClick={() => { setPane('model') }}>
+                <span className={css.cellLabel}>Model</span>
+                <span className={css.cellValue}>{modelLabel}</span>
+                <IconChevronRightOutline14 className={css.cellChevron} />
+              </button>
+              {reasoning !== undefined && (
+                <button ref={itemRef()} type="button" role="menuitem" className={css.cell} onClick={() => { setPane('effort') }}>
+                  <span className={css.cellLabel}>Effort</span>
+                  <span className={css.cellValue}>{effortLabel}</span>
+                  <IconChevronRightOutline14 className={css.cellChevron} />
+                </button>
+              )}
+            </>
+          )}
+
+          {pane === 'model' && (
+            <>
+              {state.status === 'loading' && (
+                <div className={css.status}>正在刷新模型列表…</div>
+              )}
+              {state.error !== null && (
+                <div className={css.error}>
+                  <span>模型操作失败：{state.error}</span>
+                  <button type="button" className={css.retry} onClick={() => { load() }}>重试</button>
+                </div>
+              )}
+              {state.failures.map(failure => (
+                <div className={css.warning} key={failure.id}>
+                  <span>{failure.name} 加载失败：{failure.message}</span>
+                  <button type="button" className={css.retry} onClick={() => { load() }}>重试</button>
+                </div>
+              ))}
+              <div className={clsx(css.groups, 'scrollable')}>
+                {state.groups.map((group) => {
+                  const headingId = `${id}-${group.id}`
+                  return (
+                    <section role="group" aria-labelledby={headingId} className={css.group} key={group.id}>
+                      <div className={css.groupTitle} id={headingId}>{group.name}</div>
+                      {group.models.map((model) => {
+                        const selected = state.current?.provider === group.id && state.current.model === model.id
+                        return (
+                          <button
+                            ref={itemRef()}
+                            type="button"
+                            role="menuitemradio"
+                            aria-checked={selected}
+                            className={clsx(css.option, selected && css.selected)}
+                            key={model.id}
+                            title={model.name}
+                            disabled={busy}
+                            onClick={() => { choose({ provider: group.id, model: model.id }) }}
+                          >
+                            <span className={css.optionCopy}>
+                              <span className={css.modelName}>{model.name}</span>
+                              {model.description !== undefined && (
+                                <span className={css.description}>{model.description}</span>
+                              )}
+                              {model.unlisted === true && (
+                                <span className={css.unlisted}>当前模型 · 未列入目录</span>
+                              )}
+                            </span>
+                            <span className={css.check}>
+                              {selected ? <IconCheckOutline16 /> : null}
+                            </span>
+                          </button>
+                        )
+                      })}
+                    </section>
+                  )
+                })}
+              </div>
+              {state.status === 'ready' && choices.length === 0 && (
+                <div className={css.empty}>没有可用的模型。</div>
+              )}
+            </>
+          )}
+
+          {pane === 'effort' && (
+            <>
+              {state.error !== null && (
+                <div className={css.error}>
+                  <span>模型操作失败：{state.error}</span>
+                  <button type="button" className={css.retry} onClick={() => { load() }}>重新加载</button>
+                </div>
+              )}
+              {effortChoices.length === 0
+                ? <div className={css.empty}>当前模型未提供推理等级。</div>
+                : effortChoices.map(level => (
+                  <button
+                    ref={itemRef()}
+                    type="button"
+                    role="menuitemradio"
+                    aria-checked={effectiveEffort === level.effort}
+                    className={clsx(css.option, effectiveEffort === level.effort && css.selected)}
+                    key={level.key}
+                    disabled={busy}
+                    onClick={() => { chooseEffort(level.effort) }}
+                  >
+                    <span className={css.optionCopy}>
+                      <span className={css.modelName}>{level.label}</span>
+                      {level.description !== undefined && (
+                        <span className={css.description}>{level.description}</span>
+                      )}
+                    </span>
+                    <span className={css.check}>
+                      {effectiveEffort === level.effort ? <IconCheckOutline16 /> : null}
+                    </span>
+                  </button>
+                ))}
+            </>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

packages/client/ui-model/src/client/directory.ts

@@ -0,0 +1,126 @@
+/**
+ * Per-session model directory: the ONE state both selection entries share.
+ * The /model popup and the composer-seat selector load through the same
+ * controller and submit through the same selectModel call, so the host stays
+ * the single fact source and the store is one shared echo — a switch made in
+ * either entry is what the other shows next.
+ */
+import type {
+  IApiClient, ModelCatalogFailure, ModelProviderGroup, ModelTarget, SessionId, SessionModels,
+} from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Directory snapshot both entries render from. */
+export interface ModelDirectoryState {
+  /** Target the host reports for the next assembled step; null before the first load. */
+  current: ModelTarget | null
+  /** Successfully loaded provider groups (last good load). */
+  groups: readonly ModelProviderGroup[]
+  /** Provider-local failures from the last load; usable groups stay usable. */
+  failures: readonly ModelCatalogFailure[]
+  /** Lifecycle of the in-flight operation. */
+  status: 'idle' | 'loading' | 'ready' | 'selecting' | 'error'
+  /** Whole-request or selection failure text; null when none. */
+  error: string | null
+}
+
+/** One session's shared directory controller; disposed with the session scope. */
+export class ModelDirectory {
+  /** The shared snapshot both entries render from (uSES-safe store). */
+  readonly store: SnapshotStore<ModelDirectoryState> = createSnapshotStore<ModelDirectoryState>({
+    current: null, groups: [], failures: [], status: 'idle', error: null,
+  })
+
+  /** Latest operation wins; an older response never overwrites a newer one. */
+  private generation = 0
+  private disposed = false
+
+  /**
+   * @param sessions - the session wire face (captured from the plugin's root connection).
+   * @param sessionId - the owning session.
+   */
+  constructor(
+    private readonly sessions: Pick<IApiClient['sessions'], 'models' | 'selectModel'>,
+    private readonly sessionId: SessionId,
+  ) {}
+
+  /**
+   * Refresh the advisory directory (both entries call this on open).
+   * Failure preserves the last good groups and current target.
+   * @returns the fresh directory value.
+   */
+  async load(): Promise<SessionModels> {
+    const generation = ++this.generation
+    this.store.update((s) => { s.status = 'loading'; s.error = null })
+    const { result } = await this.sessions.models({ sessionId: this.sessionId })
+    if (this.disposed || generation !== this.generation) {
+      if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`)
+      return result.value
+    }
+    if (!result.ok) {
+      this.store.update((s) => { s.status = 'error'; s.error = `${result.error.code}: ${result.error.message}` })
+      throw new Error(`session.models failed: ${result.error.code}: ${result.error.message}`)
+    }
+    const { current, groups, failures } = result.value
+    this.store.update((s) => {
+      s.current = current
+      s.groups = groups
+      s.failures = failures
+      s.status = 'ready'
+      s.error = null
+    })
+    return result.value
+  }
+
+  /**
+   * Select the complete provider/model/reasoning target (both entries submit through here). Success
+   * updates the shared current; failure surfaces on the store and throws so
+   * each entry's own retry surface engages.
+   * @param target - provider, provider-owned model id, and optional adapter-owned effort.
+   */
+  async select(target: ModelTarget): Promise<void> {
+    const generation = ++this.generation
+    this.store.update((s) => { s.status = 'selecting'; s.error = null })
+    const { result } = await this.sessions.selectModel({
+      sessionId: this.sessionId,
+      provider: target.provider,
+      model: target.model,
+      ...target.reasoningEffort === undefined
+        ? {}
+        : { reasoningEffort: target.reasoningEffort },
+    })
+    if (this.disposed || generation !== this.generation) {
+      if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`)
+      return
+    }
+    if (!result.ok) {
+      this.store.update((s) => { s.status = 'error'; s.error = `${result.error.code}: ${result.error.message}` })
+      throw new Error(`session.selectModel failed: ${result.error.code}: ${result.error.message}`)
+    }
+    this.store.update((s) => { s.current = result.value.selected; s.status = 'ready'; s.error = null })
+  }
+
+  /**
+   * Drop the previous Host generation's projection and repull it. Clearing
+   * first prevents an unconsumed process-local selection from being displayed
+   * while the restarted Host has restored the last logged request target.
+   */
+  resetConnected(): void {
+    if (this.disposed) return
+    ++this.generation
+    this.store.update((s) => {
+      s.current = null
+      s.groups = []
+      s.failures = []
+      s.status = 'idle'
+      s.error = null
+    })
+    void this.load().catch(() => { /* the next menu open remains the explicit retry surface */ })
+  }
+
+  /** Scope teardown: late settlements lose write access to the store. */
+  dispose(): void {
+    this.disposed = true
+  }
+}

packages/client/ui-model/src/client/index.ts

@@ -0,0 +1,130 @@
+/**
+ * Model selection plugin, browser half — TWO entries over ONE per-session
+ * directory owned by ModelService (`ctx.models`). The /model popupSelect
+ * contribution and the composer's named `conversation.input.model` seat both
+ * load the session's provider-grouped advisory directory (`session.models`)
+ * and submit through `session.selectModel` via the same directory instance,
+ * so the host-reported current target is the single fact both surfaces echo
+ * — a switch made in either entry is what the other shows next. Failures
+ * ride each entry's own retry surface (popup shell error/retry; seat menu
+ * inline error) without forking the state.
+ */
+import type { ModelTarget, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { CommandServiceContract, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
+// Type-only: pulls the ui-conversation SlotMap merge (the input.model seat).
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ModelDirectoryState } from './directory.ts'
+import { ModelService } from './service.ts'
+import type { ModelSelectInjected } from './slots.ts'
+import { ModelSelect } from './ModelSelect.tsx'
+
+export { ModelDirectory } from './directory.ts'
+export type { ModelDirectoryState } from './directory.ts'
+export { ModelService } from './service.ts'
+export type { ModelSelectInjected } from './slots.ts'
+
+/** One selectable row's id: an opaque row key (resolved by lookup, never parsed). */
+function rowId(providerId: string, modelId: string): string {
+  return `${providerId}/${modelId}`
+}
+
+/** Flatten the directory into popup rows; failure rows are listed for visibility but never selectable. */
+function optionsOf(directory: SessionModels): SelectOption[] {
+  const rows: SelectOption[] = []
+  for (const group of directory.groups) {
+    for (const model of group.models) {
+      rows.push({
+        id: rowId(group.id, model.id),
+        label: model.name,
+        detail: model.unlisted === true
+          ? `${group.name} · 未列入目录`
+          : model.description !== undefined ? `${group.name} · ${model.description}` : group.name,
+        ...(directory.current.provider === group.id && directory.current.model === model.id
+          ? { active: true } : {}),
+      })
+    }
+  }
+  for (const failure of directory.failures) {
+    rows.push({ id: `failure/${failure.id}`, label: failure.name, detail: `目录加载失败：${failure.message}` })
+  }
+  return rows
+}
+
+/**
+ * Resolve a picked row back to its target by matching against the loaded
+ * groups (the same data the rows were built from — ids stay opaque).
+ * @param state - the session's directory snapshot.
+ * @param id - the picked row id.
+ * @returns the row's target, or undefined for failure rows / stale ids.
+ */
+function targetOf(state: ModelDirectoryState, id: string): ModelTarget | undefined {
+  for (const group of state.groups) {
+    for (const model of group.models) {
+      if (rowId(group.id, model.id) !== id) continue
+      const sameRoute = state.current?.provider === group.id && state.current.model === model.id
+      const reasoningEffort = sameRoute
+        ? state.current?.reasoningEffort ?? model.reasoning?.defaultEffort
+        : model.reasoning?.defaultEffort
+      return {
+        provider: group.id,
+        model: model.id,
+        ...reasoningEffort === undefined ? {} : { reasoningEffort },
+      }
+    }
+  }
+  return undefined
+}
+
+/** Required services: the contribution registry, the seat's slot registry, and the service's own faces. */
+export const inject = ['command', 'connection', 'sessions', 'slots']
+
+/**
+ * Client plugin body: mount ModelService, then register the /model popup
+ * contribution and the composer model seat over it.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.plugin(ModelService)
+
+  // Entry 1: the /model popupSelect over the shared directory.
+  ctx.inject(['command', 'models'], (scope: ClientContext) => {
+    const command = scope.get('command') as CommandServiceContract
+    const models = scope.models
+    scope.effect(() => command.register({
+      name: 'model',
+      description: 'Select the model for this conversation',
+      available: () => true,
+      ui: {
+        kind: 'popupSelect',
+        options: async session => optionsOf(await models.directoryFor(session.sessionId).load()),
+        onSelect: async (option, session) => {
+          const directory = models.directoryFor(session.sessionId)
+          const target = targetOf(directory.store.getSnapshot(), option.id)
+          if (target === undefined) {
+            throw new Error('this provider\'s catalog failed to load — pick a model from a loaded group')
+          }
+          await directory.select(target)
+        },
+      },
+    }), 'ui-model: /model contribution')
+  })
+
+  // Entry 2: the composer's named model seat over the SAME directory.
+  // Conditional mount: the seat is declared by the composer-bar entry; the
+  // conversation service's presence is the registration-safe signal.
+  ctx.inject(['slots', 'conversation', 'models'], (scope: ClientContext) => {
+    const models = scope.models
+    scope.effect(() => scope.slots.register({
+      name: 'conversation.input.model',
+      inject: (sessionId): ModelSelectInjected => {
+        const directory = models.directoryFor(sessionId)
+        return {
+          directory: directory.store,
+          load: () => { directory.load().catch(() => { /* surfaced on the store */ }) },
+          select: (target: ModelTarget) => directory.select(target).then(() => true, () => false),
+        }
+      },
+    }, ModelSelect), 'ui-model: composer model seat registration')
+  })
+}

packages/client/ui-model/src/client/service.ts

@@ -0,0 +1,71 @@
+/**
+ * ModelService (`ctx.models`): the root owner of per-session
+ * {@link ModelDirectory} instances. Both selection entries (the /model popup
+ * and the composer model seat) resolve their session's directory through
+ * this service, which is what makes the dual entry one shared state.
+ *
+ * Per-session storage follows the client service pattern (SlashService /
+ * CommandService): a lazy service-internal map whose entry is deleted by the
+ * owning scope's disposer. The host `dsh-scope` ScopedLayers registry does
+ * not transplant here: it derives scope from the host carrier mechanism
+ * (object-keyed), while client scopes tag contexts with branded SessionId
+ * strings, and it models global+shadow named registries — this is a
+ * per-session singleton with no global layer to merge.
+ */
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { ModelDirectory } from './directory.ts'
+
+declare module 'cordis' {
+  interface Context {
+    models: ModelService
+  }
+}
+
+/** Live mutable state in one holder (service methods run behind the caller-ctx tracker). */
+interface LiveState {
+  /** Per-session directories; entries are deleted by their scope disposer. */
+  readonly directories: Map<SessionId, ModelDirectory>
+}
+
+/** The `ctx.models` session model-selection service. */
+export class ModelService extends Service {
+  static inject = ['connection', 'sessions']
+
+  private readonly live: LiveState = { directories: new Map() }
+
+  /**
+   * @param ctx - owning root context (the service registers itself as `models`).
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'models')
+    ctx.on('connection/reset', () => {
+      for (const directory of this.live.directories.values()) directory.resetConnected()
+    })
+  }
+
+  /**
+   * Resolve the per-session shared directory (lazy; the scope disposer
+   * removes and disposes it). Unknown sessions fail loud.
+   * @param sessionId - the owning session.
+   * @returns the resident directory both entries share.
+   */
+  directoryFor(sessionId: SessionId): ModelDirectory {
+    const { live } = this
+    const existing = live.directories.get(sessionId)
+    if (existing !== undefined) return existing
+    const sessions = this.ctx.get('sessions') as SessionsService
+    const actx = sessions.scope(sessionId)
+    if (actx === undefined) throw new Error(`ui-model: session "${String(sessionId)}" resolved no scope`)
+    const connection = this.ctx.get('connection') as ConnectionHandle
+    const directory = new ModelDirectory(connection.api.sessions, sessionId)
+    live.directories.set(sessionId, directory)
+    actx.effect(() => () => {
+      directory.dispose()
+      live.directories.delete(sessionId)
+    }, 'ui-model: session directory')
+    return directory
+  }
+}

packages/client/ui-model/src/client/slots.ts

@@ -0,0 +1,23 @@
+/**
+ * ModelSelect's injected face. The target 'conversation.input.model' seat is
+ * declared (children table) and typed by ui-conversation's composer-bar
+ * entry; this package only contributes the single occupant, so no SlotMap
+ * merge lives here.
+ */
+import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ModelDirectoryState } from './directory.ts'
+
+/** Injected business face of the composer model seat. */
+export interface ModelSelectInjected {
+  /** The session's shared directory store (same instance the /model popup reads). */
+  directory: SnapshotStore<ModelDirectoryState>
+  /** Refresh the advisory directory (fire-and-forget; errors land on the store). */
+  load: () => void
+  /**
+   * Select a complete provider/model/reasoning target through the shared route.
+   * @param target - model target and optional adapter-owned effort.
+   * @returns whether the host accepted the selection.
+   */
+  select: (target: ModelTarget) => Promise<boolean>
+}

packages/client/ui-model/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-model/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Model selection plugin, node half. Pure UI plugin: the empty apply exists
+ * so the plugin appears in the host cordis.yml / Loader; the browser half
+ * ships via exports["./client"], discovered through the package.json
+ * dshClient declaration.
+ */
+
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export function apply(): void {}

packages/client/ui-model/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-model`.
+ * @module @deepseek-ai/dsh-client-ui-model/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-model'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-model-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a single command contribution registration whose disposal is
+ * proven by the HMR-safety spec — it emits no cordis events and owns no
+ * cross-plugin mutable state.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/ui-model/tests/browser-plugin.spec.ts

@@ -0,0 +1,210 @@
+/**
+ * ui-model browser half on a real cordis Context with fake command/slots/
+ * connection faces and real session scopes: the plugin mounts ModelService
+ * as `models`, the /model contribution and the conversation.input.model
+ * seat both register, and BOTH entries resolve the SAME per-session
+ * directory through the service — a selection submitted through the seat's
+ * inject face is the current the popup's next options pass marks active
+ * (and the reverse), the one-shared-state contract of the dual entry.
+ * Scope disposal drops the directory (HMR safety).
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { createScope } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { CommandContribution, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
+import type { ModelSelectInjected } from '../src/client/slots.ts'
+import { apply, inject } from '../src/client/index.ts'
+
+const sid = (k: string): SessionId => k as SessionId
+
+const GROUPS = [{
+  id: 'deepseek',
+  name: 'DeepSeek',
+  models: [
+    {
+      id: 'deepseek-v4-flash',
+      name: 'DeepSeek-V4-Flash',
+      reasoning: {
+        efforts: [
+          { id: 'off', name: 'Off' },
+          { id: 'high', name: 'High' },
+          { id: 'max', name: 'Max' },
+        ],
+        defaultEffort: 'high',
+      },
+    },
+    {
+      id: 'deepseek-v4-pro',
+      name: 'DeepSeek-V4-Pro',
+      reasoning: {
+        efforts: [
+          { id: 'off', name: 'Off' },
+          { id: 'high', name: 'High' },
+          { id: 'max', name: 'Max' },
+        ],
+        defaultEffort: 'high',
+      },
+    },
+  ],
+}]
+
+/** Boot the plugin over fake faces + a stateful fake host (current moves on selectModel). */
+async function bench() {
+  const ctx = new Context()
+  let current: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' }
+  const calls = { models: 0, select: 0 }
+  ctx.provide('connection', { api: { sessions: {
+    models: () => {
+      calls.models += 1
+      return Promise.resolve({ result: { ok: true as const, value: { current, groups: GROUPS, failures: [] } } })
+    },
+    selectModel: (payload: { provider: string; model: string; reasoningEffort?: string }) => {
+      calls.select += 1
+      current = {
+        provider: payload.provider,
+        model: payload.model,
+        ...payload.reasoningEffort === undefined
+          ? {}
+          : { reasoningEffort: payload.reasoningEffort },
+      }
+      return Promise.resolve({ result: { ok: true as const, value: { selected: current } } })
+    },
+  } } })
+  let contribution: CommandContribution | undefined
+  ctx.provide('command', {
+    register(c: CommandContribution) {
+      contribution = c
+      return () => { contribution = undefined }
+    },
+  })
+  const seats = new Map<string, { inject: ((sessionId: SessionId) => ModelSelectInjected) | undefined }>()
+  ctx.provide('slots', {
+    register(options: { name: string; inject?: (sessionId: SessionId) => ModelSelectInjected }) {
+      seats.set(options.name, { inject: options.inject })
+      return () => { seats.delete(options.name) }
+    },
+  })
+  ctx.provide('conversation', {})
+  const scopes = new Map<SessionId, Context>()
+  ctx.provide('sessions', { scope: (id: SessionId) => scopes.get(id) })
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  await ctx.plugin(function probe() {}).await()
+  const mint = (key: string) => {
+    const handle = createScope(ctx, sid(key))
+    scopes.set(sid(key), handle.ctx)
+    return handle
+  }
+  return {
+    ctx, fiber, mint, calls,
+    contribution: () => contribution!,
+    seat: () => seats.get('conversation.input.model')!,
+    hostCurrent: () => current,
+    setHostCurrent: (target: ModelTarget) => { current = target },
+  }
+}
+
+const projection = (id: string) => ({ sessionId: sid(id) })
+
+describe('ui-model dual entry', () => {
+  it('registers the /model contribution and the composer model seat', async () => {
+    const b = await bench()
+    expect(b.contribution().name).toBe('model')
+    expect(b.contribution().ui.kind).toBe('popupSelect')
+    expect(b.seat().inject).toBeTypeOf('function')
+  })
+
+  it('popup options mark the host current active with the provider group in the detail', async () => {
+    const b = await bench()
+    b.mint('s1')
+    const options = await b.contribution().ui.options(projection('s1'), new AbortController().signal)
+    expect(options.map((o: SelectOption) => o.label)).toEqual(['DeepSeek-V4-Flash', 'DeepSeek-V4-Pro'])
+    expect(options[0]).toMatchObject({ active: true, detail: 'DeepSeek' })
+    expect(options[1]?.active).toBeUndefined()
+  })
+
+  it('a seat selection is the current the popup marks active next — one shared state', async () => {
+    const b = await bench()
+    b.mint('s1')
+    const seatFace = b.seat().inject!(sid('s1'))
+    // Switch through the SEAT entry.
+    expect(await seatFace.select({
+      provider: 'deepseek',
+      model: 'deepseek-v4-pro',
+      reasoningEffort: 'max',
+    })).toBe(true)
+    expect(b.hostCurrent()).toEqual({
+      provider: 'deepseek',
+      model: 'deepseek-v4-pro',
+      reasoningEffort: 'max',
+    })
+    expect(seatFace.directory.getSnapshot().current).toEqual({
+      provider: 'deepseek',
+      model: 'deepseek-v4-pro',
+      reasoningEffort: 'max',
+    })
+    // The POPUP's next options pass reflects it without a seat-side reload.
+    const options = await b.contribution().ui.options(projection('s1'), new AbortController().signal)
+    expect(options.find((o: SelectOption) => o.label === 'DeepSeek-V4-Pro')).toMatchObject({ active: true })
+  })
+
+  it('a popup selection lands on the seat store — the reverse direction of the same state', async () => {
+    const b = await bench()
+    b.mint('s1')
+    const seatFace = b.seat().inject!(sid('s1'))
+    const options = await b.contribution().ui.options(projection('s1'), new AbortController().signal)
+    const pro = options.find((o: SelectOption) => o.label === 'DeepSeek-V4-Pro')!
+    await b.contribution().ui.onSelect(pro, projection('s1'))
+    expect(seatFace.directory.getSnapshot().current).toEqual({
+      provider: 'deepseek',
+      model: 'deepseek-v4-pro',
+      reasoningEffort: 'high',
+    })
+  })
+
+  it('both entries share one directory instance per session, isolated across sessions', async () => {
+    const b = await bench()
+    b.mint('a')
+    b.mint('b')
+    const faceA = b.seat().inject!(sid('a'))
+    const faceA2 = b.seat().inject!(sid('a'))
+    const faceB = b.seat().inject!(sid('b'))
+    expect(faceA.directory).toBe(faceA2.directory)
+    expect(faceA.directory).not.toBe(faceB.directory)
+    // The service face resolves the same instance the seat inject handed out.
+    expect(b.ctx.models.directoryFor(sid('a')).store).toBe(faceA.directory)
+  })
+
+  it('drops an unconsumed local selection and restores the Host target after reconnect', async () => {
+    const b = await bench()
+    b.mint('s1')
+    const face = b.seat().inject!(sid('s1'))
+    await face.select({ provider: 'deepseek', model: 'deepseek-v4-pro' })
+    b.setHostCurrent({ provider: 'deepseek', model: 'deepseek-v4-flash' })
+
+    b.ctx.emit('connection/reset')
+    expect(face.directory.getSnapshot()).toMatchObject({ current: null, status: 'loading' })
+    await Promise.resolve()
+    expect(face.directory.getSnapshot()).toMatchObject({
+      current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      status: 'ready',
+    })
+  })
+
+  it('scope disposal drops the directory; a reborn scope gets a fresh one', async () => {
+    const b = await bench()
+    const first = b.mint('s1')
+    const face1 = b.seat().inject!(sid('s1'))
+    await first.fiber.dispose()
+    b.mint('s1')
+    const face2 = b.seat().inject!(sid('s1'))
+    expect(face2.directory).not.toBe(face1.directory)
+  })
+
+  it('an unknown session fails loud at the seat inject', async () => {
+    const b = await bench()
+    expect(() => b.seat().inject!(sid('ghost'))).toThrow(/resolved no scope/)
+  })
+})

packages/client/ui-model/tests/model-select.spec.tsx

@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ModelDirectoryState } from '../src/client/directory.ts'
+import { ModelSelect } from '../src/client/ModelSelect.tsx'
+
+const reasoning = {
+  efforts: [
+    { id: 'off', name: 'Off' },
+    { id: 'high', name: 'High' },
+    { id: 'max', name: 'Max', description: 'Largest budget' },
+  ],
+  defaultEffort: 'high',
+}
+
+function state(overrides: Partial<ModelDirectoryState> = {}): ModelDirectoryState {
+  return {
+    current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    groups: [{
+      id: 'deepseek',
+      name: 'DeepSeek',
+      models: [{ id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', reasoning }],
+    }],
+    failures: [],
+    status: 'ready',
+    error: null,
+    ...overrides,
+  }
+}
+
+afterEach(cleanup)
+
+describe('ModelSelect reasoning effort', () => {
+  it('renders adapter metadata and submits the effort as part of the session target', async () => {
+    const directory = createSnapshotStore(state())
+    const select = vi.fn(async (target: ModelTarget) => {
+      directory.update((snapshot) => { snapshot.current = target })
+      return true
+    })
+    render(<ModelSelect
+      locked={false}
+      directory={directory}
+      load={vi.fn()}
+      select={select}
+    />)
+
+    const trigger = screen.getByRole('button', {
+      name: '选择模型，当前 DeepSeek-V4-Flash，推理等级 High',
+    })
+    fireEvent.click(trigger)
+    fireEvent.click(screen.getByRole('menuitem', { name: /Effort/ }))
+    expect(screen.getAllByRole('menuitemradio').map(item => item.textContent))
+      .toEqual(['Off', 'High', 'MaxLargest budget'])
+
+    fireEvent.click(screen.getByRole('menuitemradio', { name: /Max/ }))
+    await waitFor(() => {
+      expect(select).toHaveBeenCalledWith({
+        provider: 'deepseek',
+        model: 'deepseek-v4-flash',
+        reasoningEffort: 'max',
+      })
+      expect(trigger.getAttribute('aria-label')).toBe('选择模型，当前 DeepSeek-V4-Flash，推理等级 Max')
+    })
+  })
+
+  it('offers provider default only when the adapter does not configure a model default', () => {
+    const directory = createSnapshotStore(state({
+      groups: [{
+        id: 'provider',
+        name: 'Provider',
+        models: [{
+          id: 'model',
+          name: 'Model',
+          reasoning: { efforts: [{ id: 'standard', name: 'Standard' }] },
+        }],
+      }],
+      current: { provider: 'provider', model: 'model' },
+    }))
+    render(<ModelSelect
+      locked={false}
+      directory={directory}
+      load={vi.fn()}
+      select={vi.fn().mockResolvedValue(true)}
+    />)
+
+    fireEvent.click(screen.getByRole('button', {
+      name: '选择模型，当前 Model，推理等级 Provider default',
+    }))
+    fireEvent.click(screen.getByRole('menuitem', { name: /Effort/ }))
+    expect(screen.getAllByRole('menuitemradio').map(item => item.textContent))
+      .toEqual(['Provider default', 'Standard'])
+  })
+})

packages/client/ui-model/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-command"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slash"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-model/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-model', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/core/agent-loop/src/agent.ts

@@ -190,7 +190,7 @@ export class ReactLoopAgent implements Agent {
     // but the waiter must not gamble quiescence on that: a future escape
     // still counts as settled activity.
     /* v8 ignore next 3 -- the catch arm backstops rejection paths that are all currently contained */
-    while (this.wakeScheduled || this.abort !== undefined || this.queued.some(item => item.wakeup)) {
+    while (this.busy || this.wakeScheduled || this.abort !== undefined || this.queued.some(item => item.wakeup)) {
       await this.done.catch(() => undefined)
     }
   }
@@ -428,6 +428,15 @@ export class ReactLoopAgent implements Agent {
       signal.removeEventListener('abort', cancelRetry)
     }
 
+    if (opened) {
+      try {
+        await this.loopCtx.sessions.flush(this.session)
+      } catch (error: unknown) {
+        this.loopCtx.logger.warn(`agent "${this.id}": session/flush failed at turn ${turn}: ${errorChain(error)}`)
+        emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error)
+      }
+    }
+
     if (retryFailures !== undefined) {
       await this.run({ kind: 'retry' }, [], 0, retryFailures)
     } else {

packages/core/agent-loop/tests/agent.spec.ts

@@ -88,6 +88,79 @@ describe('Agent', () => {
     expect(statuses).toEqual(['running', 'idle'])
   })
 
+  it('awaits the turn-end checkpoint before claiming the next queued turn', async () => {
+    const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const firstFlush = Promise.withResolvers<undefined>()
+    const flushedTurns: number[] = []
+    ctx.on('session/flush', async (session) => {
+      const turnEnd = session.events.findLast(event => event.type === 'turn/end')
+      flushedTurns.push(turnEnd?.data.turn ?? 0)
+      if (turnEnd?.data.turn === 1) await firstFlush.promise
+    })
+
+    send(agent, 'first')
+    send(agent, 'second')
+
+    await vi.waitFor(() => { expect(flushedTurns).toEqual([1]) })
+    expect(adapter.requests).toHaveLength(1)
+    firstFlush.resolve(undefined)
+    await agent.whenIdle()
+
+    expect(adapter.requests).toHaveLength(2)
+    expect(flushedTurns).toEqual([1, 2])
+  })
+
+  it('keeps whenIdle pending through the final turn checkpoint', async () => {
+    const ctx = await harness(new MockAdapter([textResponse('done')]))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const flush = Promise.withResolvers<undefined>()
+    let flushStarted = false
+    ctx.on('session/flush', () => {
+      flushStarted = true
+      return flush.promise
+    })
+
+    send(agent, 'go')
+    await vi.waitFor(() => { expect(flushStarted).toBe(true) })
+    let idleSettled = false
+    const idle = agent.whenIdle().then(() => { idleSettled = true })
+    await Promise.resolve()
+    expect(idleSettled).toBe(false)
+
+    flush.resolve(undefined)
+    await idle
+    expect(agent.status).toBe('idle')
+  })
+
+  it('reports a rejected turn-end checkpoint and continues queued work', async () => {
+    const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
+    const ctx = await harness(adapter)
+    const warning = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const failure = new Error('disk unavailable')
+    const errors: { turn: number; step: number; error: unknown }[] = []
+    let flushes = 0
+    ctx.on('session/flush', () => {
+      flushes += 1
+      if (flushes === 1) throw failure
+    })
+    ctx.on('agent/error', (subject, turn, step, error) => {
+      if (subject === agent) errors.push({ turn, step, error })
+    })
+
+    send(agent, 'first')
+    send(agent, 'second')
+    await agent.whenIdle()
+
+    expect(adapter.requests).toHaveLength(2)
+    expect(flushes).toBe(2)
+    expect(errors).toEqual([{ turn: 1, step: 1, error: failure }])
+    expect(warning).toHaveBeenCalledWith(expect.stringContaining('session/flush failed at turn 1: disk unavailable'))
+    warning.mockRestore()
+  })
+
   it('whenIdle() resolves immediately without active work', async () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

packages/guard/repeat-tool-guard/README.i18n.yaml

@@ -1,6 +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
-README.md: b9d6337d2145d279758f5494c2ad51ed5e00154f
-README.zh.md: 99190c262b015bf28627debd68e67f6c64618a09
+#   pnpm run verify-translation-pairing --write packages/guard/repeat-tool-guard/README.md
+README.md: 226dba10239031e8e79bd5698e77c213688ce579
+README.zh.md: 8e22a5e67d3700024934437c5c9c1a5e969b740d

packages/guard/repeat-tool-guard/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-An advisory loop-breaker, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The decision (retry differently, gather more evidence, or finish) stays entirely with the model: a legitimately repeated call is delayed by nothing and blocked by nothing. Decision record: [the repeat-tool-guard Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md).
+An advisory loop-breaker, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The decision (retry differently, gather more evidence, or finish) stays entirely with the model: a legitimately repeated call is delayed by nothing and blocked by nothing. Decision record: [the repeat-tool-guard Agent Note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md).
 
 ## Config
 

packages/guard/repeat-tool-guard/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是一个仅提供建议的循环中断器，而非面向模型的工具：它不会出现在工具列表中，不会否决或改写调用，只增加一种行为。它监视每个 agent（智能体）的工具调用流，统计以完全相同的规范化参数连续调用同一工具的次数；达到所配置的连续次数时，它会注入逐级增强的提示，要求模型停止重复、重新阅读上一次结果，并改用其他方案或结束任务。究竟是换一种方式重试、收集更多证据还是完成任务，仍完全由模型决定：合理的重复调用既不会延迟，也不会受阻。决策记录见 [repeat-tool-guard Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md)。
+这是一个仅提供建议的循环中断器，而非面向模型的工具：它不会出现在工具列表中，不会否决或改写调用，只增加一种行为。它监视每个 agent（智能体）的工具调用流，统计以完全相同的规范化参数连续调用同一工具的次数；达到所配置的连续次数时，它会注入逐级增强的提示，要求模型停止重复、重新阅读上一次结果，并改用其他方案或结束任务。究竟是换一种方式重试、收集更多证据还是完成任务，仍完全由模型决定：合理的重复调用既不会延迟，也不会受阻。决策记录见 [repeat-tool-guard Agent Note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md)。
 
 ## 配置
 

packages/host/apiproxy/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 253c0974cc1427fb7140c332fabdccbfc049ae86
-README.zh.md: d79628ca3e1f1d06ad94a0dada16e2208af3cd2c
+README.md: d6db9a9541b0727b61dbe501f7234564ffef139e
+README.zh.md: 4175c8fdb98aad2882718a2c95cd9e45825d787d

packages/host/apiproxy/README.md

@@ -12,6 +12,8 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc
 
 The mux stream projects the latest log-backed title as a validated `session/title` control frame after each attached-session subscription baseline and immediately after the corresponding live raw title event. This projection does not add titles to `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.
 
+Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target with provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`.
+
 Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `workspace.delete` removes only the Workspace registration, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed`, `host/workspace-removed`, plus `host/session-added` carry committed increments in either arrival order. Registration deletion preserves the directory and session logs; its Sessions remain in `session.list` and become Ungrouped. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.
 
 `host.pickDirectory` opens one native directory picker and returns its selected path, or `null` when the user cancels. Its host implementation invokes platform tools without a shell: `osascript` on macOS, an STA PowerShell `FolderBrowserDialog` on Windows, and Zenity with a KDialog fallback on Linux. The picker function is injectable for tests. This user-paced method is the sole unary call exempt from the default 30-second timeout; caller and connection aborts still propagate to the native process. The browser carrier separately restricts this privileged method to loopback, same-origin requests.

packages/host/apiproxy/README.zh.md

@@ -12,6 +12,8 @@
 
 mux 流会在每个已附加会话的订阅基线之后，以及对应的实时原始标题事件之后，立即把基于日志的最新标题投影为经过校验的 `session/title` 控制帧。该投影不会把标题加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。
 
+会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理（reasoning）目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
+
 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
 
 `host.pickDirectory` 会打开一个原生目录选择器并返回选中的路径；用户取消时返回 `null`。宿主实现不经 shell 调用平台工具：macOS 使用 `osascript`，Windows 使用以 STA 模式运行的 PowerShell `FolderBrowserDialog`，Linux 使用 Zenity，并以 KDialog 作为回退。选择器函数可在测试中注入。该方法需等待用户完成操作，是唯一不受默认 30 秒超时限制的一元调用；调用方发出的中止信号和连接中止仍会传播至原生进程。浏览器载体另行将这一特权方法限制为仅接受来自回环地址的同源请求。

packages/host/apiproxy/src/api-proxy.ts

@@ -7,7 +7,11 @@ import { randomUUID } from 'node:crypto'
 import { mkdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Context } from 'cordis'
-import type { Agent, AgentMessage, AgentMessageId, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
+import type {
+  Agent, AgentLlmTarget, AgentLlmTargetRef, AgentMessage, AgentMessageId, AgentStatus,
+} from '@deepseek-ai/dsh-agent'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId, TodoItem } from '@deepseek-ai/dsh-session'
@@ -21,7 +25,8 @@ import {
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
-  ApiProxy, HistoryEntry, HostFrame, MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
+  ApiProxy, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup, ModelReasoning,
+  MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
   WorkspaceId, WorkspaceView,
 } from './api/index.ts'
 // Type-only edges: resolve `ctx.get('commands')`, the `commands/change` event, and `ctx.get('skills')`.
@@ -361,6 +366,8 @@ function changedWorkspaceView(workspaceId: string, value: unknown): WorkspaceVie
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
   const agentOptions = { provider: defaults.provider, model: defaults.model }
+  type WebLlmTargetRef = AgentLlmTargetRef & { current: AgentLlmTarget }
+  const targets = new WeakMap<Agent, WebLlmTargetRef>()
   /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
   const resumes = new Map<SessionId, Promise<Agent>>()
   /** Client-chosen identity creation/resume, deduplicated across concurrent retries. */
@@ -370,6 +377,40 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   const pendingQuestions = new Map<RpcId, PendingQuestion>()
   const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
 
+  /**
+   * Install or return the session-local target that prompt assembly snapshots.
+   * Seed order: latest logged request/header, else the host default routing.
+   * There is no create-time per-session override tier on this wire — if one
+   * returns (a create-options contribution), it must fold in between the two.
+   */
+  function targetFor(agent: Agent): WebLlmTargetRef {
+    const installed = targets.get(agent)
+    if (installed !== undefined) return installed
+    const logged = agent.session.requestHeader()?.config
+    const target: WebLlmTargetRef = {
+      current: logged === undefined
+        ? { provider: defaults.provider, model: defaults.model }
+        : {
+          provider: logged.provider,
+          model: logged.model,
+          ...logged.reasoningEffort === undefined
+            ? {}
+            : { reasoningEffort: logged.reasoningEffort },
+        },
+      assembled: undefined,
+    }
+    installAgentLlmTarget(agent.ctx, target)
+    targets.set(agent, target)
+    return target
+  }
+
+  /** Pre-publication setup used by both fresh and resumed Web agents. */
+  function installTarget(agentCtx: Context): void {
+    const agent = agentCtx.agent
+    if (agent === undefined) throw new Error('api-proxy: agent setup has no scoped agent')
+    targetFor(agent)
+  }
+
   /** Send one transient frame to every connected mux consumer. */
   function broadcast(payload: MuxFrame): void {
     const envelope = frame(payload)
@@ -493,7 +534,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       resume = (async () => {
         try {
           await assertServable(sessionId)
-          const handle = await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })
+          const handle = await ctx.agents.resume({
+            resumeSessionId: sessionId,
+            agentOptions,
+            setup: installTarget,
+          })
           return handle.agent
         } finally {
           resumes.delete(sessionId)
@@ -528,7 +573,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           if (stored.cwd !== cwd) {
             throw new SessionCwdConflict(sessionId, cwd, stored.cwd)
           }
-          return (await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })).agent
+          return (await ctx.agents.resume({
+            resumeSessionId: sessionId,
+            agentOptions,
+            setup: installTarget,
+          })).agent
         }
 
         try {
@@ -536,7 +585,12 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         } catch (error: unknown) {
           throw new Error(`failed to ensure project directory "${cwd}": ${String(error)}`, { cause: error })
         }
-        return (await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })).agent
+        return (await ctx.agents.create({
+          sessionId,
+          agentOptions,
+          meta: { cwd },
+          setup: installTarget,
+        })).agent
       })().catch((error: unknown) => {
         // Another Host entry path may have published the same identity while
         // this operation crossed an asynchronous persistence/filesystem step.
@@ -672,6 +726,107 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         return ok(request, { events: entries, hasMore: page.hasMore, ...todos === undefined ? {} : { todos } })
       },
 
+      async models(request) {
+        const { sessionId } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const current = targetFor(found.agent).current
+        const catalog = await Promise.all(ctx.llm.listProviders().map(async (provider) => {
+          try {
+            const advertised = await ctx.llm.listModels(provider.id)
+            const models = [...advertised]
+            if (
+              provider.id === current.provider
+              && !models.some(model => model.id === current.model)
+            ) {
+              models.push({
+                provider: provider.id,
+                id: current.model,
+                name: current.model,
+              })
+            }
+            const entries = await Promise.all(models.map(async (model) => {
+              const resolved = await ctx.llm.resolveModelInfo(provider.id, model.id)
+              const reasoning: ModelReasoning | undefined = resolved.reasoning === undefined
+                ? undefined
+                : {
+                  efforts: resolved.reasoning.efforts.map(effort => ({
+                    id: effort.id,
+                    name: effort.name,
+                    ...effort.description === undefined
+                      ? {}
+                      : { description: effort.description },
+                  })),
+                  ...resolved.reasoning.defaultEffort === undefined
+                    ? {}
+                    : { defaultEffort: resolved.reasoning.defaultEffort },
+                }
+              return {
+                id: model.id,
+                name: model.name,
+                ...model.description === undefined ? {} : { description: model.description },
+                ...provider.id === current.provider
+                  && model.id === current.model
+                  && !advertised.some(candidate => candidate.id === current.model)
+                  ? { unlisted: true as const }
+                  : {},
+                ...reasoning === undefined ? {} : { reasoning },
+              }
+            }))
+            const group: ModelProviderGroup = {
+              id: provider.id,
+              name: provider.name,
+              models: entries,
+            }
+            return { kind: 'group' as const, group }
+          } catch (error: unknown) {
+            const failure: ModelCatalogFailure = {
+              id: provider.id,
+              name: provider.name,
+              message: error instanceof Error ? error.message : String(error),
+            }
+            return { kind: 'failure' as const, failure }
+          }
+        }))
+        const groups = catalog.flatMap(item => item.kind === 'group' ? [item.group] : [])
+        const failures = catalog.flatMap(item => item.kind === 'failure' ? [item.failure] : [])
+        return ok(request, {
+          current: { ...current },
+          groups: groups.filter(group => group.models.length > 0),
+          failures,
+        })
+      },
+
+      async selectModel(request) {
+        const { sessionId, provider, model, reasoningEffort } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        try {
+          const resolved = await ctx.llm.resolveCallConfig({
+            provider,
+            model,
+            ...reasoningEffort === undefined
+              ? {}
+              : { reasoningEffort: ReasoningEffortId(reasoningEffort) },
+          })
+          const selected: AgentLlmTarget = {
+            provider: resolved.provider,
+            model: resolved.model,
+            ...resolved.reasoningEffort === undefined
+              ? {}
+              : { reasoningEffort: resolved.reasoningEffort },
+          }
+          targetFor(found.agent).current = selected
+          return ok(request, { selected: { ...selected } })
+        } catch (error: unknown) {
+          return err(request, {
+            code: 'model-unavailable',
+            message: error instanceof Error ? error.message : String(error),
+            details: { provider, model },
+          })
+        }
+      },
+
       async prompt(request) {
         const { sessionId, mode, content } = request.payload
         const found = await agentFor(sessionId)

packages/host/apiproxy/src/api/index.ts

@@ -25,7 +25,10 @@ export interface ApiProxy {
 }
 
 // ---- Domain interfaces and payload entities ----
-export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
+export type {
+  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  ModelReasoningEffort, ModelTarget, SessionModels, SessionsApi, SessionSummary,
+} from './sessions.ts'
 export type { HostApi } from './host.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor, CommandExecuteResult } from './commands.ts'

packages/host/apiproxy/src/api/rpc-map.ts

@@ -20,6 +20,8 @@ export interface RpcMethodMap {
   'session.list': SessionsApi['list']
   'session.create': SessionsApi['create']
   'session.history': SessionsApi['history']
+  'session.models': SessionsApi['models']
+  'session.selectModel': SessionsApi['selectModel']
   'session.prompt': SessionsApi['prompt']
   'session.cancel': SessionsApi['cancel']
   'host.describe': HostApi['describe']

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -35,6 +35,7 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
   z.object({ code: z.literal('cancelled'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('model-unavailable'), message: z.string(), details: z.object({ provider: z.string(), model: z.string() }) }),
   z.object({ code: z.literal('session-conflict'), message: z.string(), details: z.object({ sessionId: z.string(), requestedCwd: z.string(), existingCwd: z.string().optional() }) }),
   z.object({ code: z.literal('workspace-attach-failed'), message: z.string(), details: z.object({ sessionId: z.string(), workspaceId: z.string() }) }),
   z.object({ code: z.literal('workspace-not-found'), message: z.string(), details: z.object({ workspaceId: z.string() }) }),

packages/host/apiproxy/src/api/rpc.ts

@@ -32,6 +32,7 @@ export interface RpcErrorDetailsMap {
   'bad-request': { issues: ZodIssue[] }
   'cancelled': {}
   'session-not-found': { sessionId: SessionId }
+  'model-unavailable': { provider: string; model: string }
   'session-conflict': { sessionId: SessionId; requestedCwd: string; existingCwd?: string }
   'workspace-attach-failed': { sessionId: SessionId; workspaceId: string }
   'workspace-not-found': { workspaceId: string }

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -9,7 +9,10 @@ import { z } from 'zod'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
-import type { HistoryEntry, SessionSummary } from './sessions.ts'
+import type {
+  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  ModelReasoningEffort, ModelTarget, SessionSummary,
+} from './sessions.ts'
 import type { ToolEventView } from './events.ts'
 import type { WorkspaceId } from './workspace.ts'
 
@@ -76,6 +79,49 @@ export const sessionHistoryRequestSchema = z.object({
   maxMessages: z.number().int().positive().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'session.history'>>>
 
+/** Complete provider/model target. */
+export const modelTargetSchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  reasoningEffort: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<ModelTarget>>
+
+/** One adapter-owned reasoning effort. */
+export const modelReasoningEffortSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+}) satisfies z.ZodType<Wire<ModelReasoningEffort>>
+
+/** Exact-model reasoning metadata. */
+export const modelReasoningSchema = z.object({
+  efforts: z.array(modelReasoningEffortSchema).min(1),
+  defaultEffort: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<ModelReasoning>>
+
+/** One advisory model entry inside a provider group. */
+export const modelCatalogModelSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  unlisted: z.literal(true).optional(),
+  reasoning: modelReasoningSchema.optional(),
+}) satisfies z.ZodType<Wire<ModelCatalogModel>>
+
+/** One successfully loaded provider group. */
+export const modelProviderGroupSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  models: z.array(modelCatalogModelSchema),
+}) satisfies z.ZodType<Wire<ModelProviderGroup>>
+
+/** One provider-local catalog failure. */
+export const modelCatalogFailureSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  message: z.string(),
+}) satisfies z.ZodType<Wire<ModelCatalogFailure>>
+
 /**
  * ToolEventView passthrough: lock only the `for` discriminant and the presence
  * of a card-tagged `view` object. The view interior is a host-computed product
@@ -106,6 +152,31 @@ export const sessionHistoryValueSchema = z.object({
   todos: z.array(todoItemSchema).optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
 
+/** session.models request payload. */
+export const sessionModelsRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.models'>>>
+
+/** session.models response value. */
+export const sessionModelsValueSchema = z.object({
+  current: modelTargetSchema,
+  groups: z.array(modelProviderGroupSchema),
+  failures: z.array(modelCatalogFailureSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.models'>>>
+
+/** session.selectModel request payload. */
+export const sessionSelectModelRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  reasoningEffort: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.selectModel'>>>
+
+/** session.selectModel response value. */
+export const sessionSelectModelValueSchema = z.object({
+  selected: modelTargetSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'session.selectModel'>>>
+
 /** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
 export const contentBlockSchema = z.looseObject({ type: z.string() })
 

packages/host/apiproxy/src/api/sessions.ts

@@ -32,6 +32,78 @@ export interface HistoryEntry {
   view?: ToolEventView
 }
 
+/** Complete model target selected for one session. */
+export interface ModelTarget {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+  /** Adapter-owned reasoning effort; absence preserves adapter/provider default behavior. */
+  reasoningEffort?: string
+}
+
+/** One adapter-owned reasoning effort displayed for an exact model route. */
+export interface ModelReasoningEffort {
+  /** Opaque value submitted back to the owning adapter. */
+  id: string
+  /** Adapter-supplied display name. */
+  name: string
+  /** Optional adapter-supplied description. */
+  description?: string
+}
+
+/** Selectable reasoning metadata for one exact model route. */
+export interface ModelReasoning {
+  /** Efforts in adapter-preferred display order. */
+  efforts: ModelReasoningEffort[]
+  /** Adapter-configured default; absence preserves the provider default. */
+  defaultEffort?: string
+}
+
+/** One model displayed inside its provider group. */
+export interface ModelCatalogModel {
+  /** Provider-owned model id. */
+  id: string
+  /** Provider-supplied display name. */
+  name: string
+  /** Optional provider-supplied description. */
+  description?: string
+  /** The current model was inserted because the advisory catalog omitted it. */
+  unlisted?: true
+  /** Exact-route reasoning metadata when the adapter exposes it. */
+  reasoning?: ModelReasoning
+}
+
+/** One provider and the models it advertised successfully. */
+export interface ModelProviderGroup {
+  /** Provider route id used for requests. */
+  id: string
+  /** Provider display name. */
+  name: string
+  /** Models in provider-preferred order. */
+  models: ModelCatalogModel[]
+}
+
+/** A provider whose asynchronous catalog lookup failed. */
+export interface ModelCatalogFailure {
+  /** Provider route id. */
+  id: string
+  /** Provider display name. */
+  name: string
+  /** Lookup failure diagnostic. */
+  message: string
+}
+
+/** Detached model-directory snapshot for one session. */
+export interface SessionModels {
+  /** Target selected for the session's next assembled step. */
+  current: ModelTarget
+  /** Successfully loaded provider groups. */
+  groups: ModelProviderGroup[]
+  /** Provider-local failures; successful groups remain usable. */
+  failures: ModelCatalogFailure[]
+}
+
 /** Session list entry (v1 builds no index: list does readdir+stat). */
 export interface SessionSummary {
   sessionId: SessionId
@@ -85,6 +157,22 @@ export interface SessionsApi {
   history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
   Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; todos?: TodoItem[] }>>
 
+  /** Reads a fresh advisory model directory for this session. Provider lookups run independently. */
+  models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>
+
+  /**
+   * Selects the complete target for this session. Exact model metadata
+   * validates an optional reasoning effort, while catalog membership remains
+   * advisory.
+   */
+  selectModel(request: RpcRequest<{
+    sessionId: SessionId
+    provider: string
+    model: string
+    reasoningEffort?: string
+  }>):
+  Promise<RpcResponse<{ selected: ModelTarget }>>
+
   /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
   prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
   Promise<RpcResponse<{ accepted: true }>>

packages/host/apiproxy/src/fetch/client.ts

@@ -19,7 +19,9 @@ import {
   sessionCreateValueSchema,
   sessionHistoryValueSchema,
   sessionListValueSchema,
+  sessionModelsValueSchema,
   sessionPromptValueSchema,
+  sessionSelectModelValueSchema,
 } from '../api/sessions.schema.ts'
 import {
   workspaceCreateValueSchema,
@@ -51,6 +53,8 @@ export interface IApiClient {
     list(payload: RequestPayload<'session.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.list'>>>
     create(payload: RequestPayload<'session.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.create'>>>
     history(payload: RequestPayload<'session.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.history'>>>
+    models(payload: RequestPayload<'session.models'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.models'>>>
+    selectModel(payload: RequestPayload<'session.selectModel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.selectModel'>>>
     prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
     cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
   }
@@ -88,6 +92,8 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.list': sessionListValueSchema,
   'session.create': sessionCreateValueSchema,
   'session.history': sessionHistoryValueSchema,
+  'session.models': sessionModelsValueSchema,
+  'session.selectModel': sessionSelectModelValueSchema,
   'session.prompt': sessionPromptValueSchema,
   'session.cancel': sessionCancelValueSchema,
   'host.describe': hostDescribeValueSchema,
@@ -288,6 +294,8 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('session.list', payload, signal),
     create: (payload, signal) => this.callUnary('session.create', payload, signal),
     history: (payload, signal) => this.callUnary('session.history', payload, signal),
+    models: (payload, signal) => this.callUnary('session.models', payload, signal),
+    selectModel: (payload, signal) => this.callUnary('session.selectModel', payload, signal),
     prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
     cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
   }

packages/host/apiproxy/src/fetch/handler.ts

@@ -19,7 +19,9 @@ import {
   sessionCreateRequestSchema,
   sessionHistoryRequestSchema,
   sessionListRequestSchema,
+  sessionModelsRequestSchema,
   sessionPromptRequestSchema,
+  sessionSelectModelRequestSchema,
 } from '../api/sessions.schema.ts'
 import { hostDescribeRequestSchema, hostPickDirectoryRequestSchema } from '../api/host.schema.ts'
 import {
@@ -52,6 +54,8 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.list': { schema: sessionListRequestSchema, invoke: (api, r) => api.sessions.list(r) },
   'session.create': { schema: sessionCreateRequestSchema, invoke: (api, r) => api.sessions.create(r) },
   'session.history': { schema: sessionHistoryRequestSchema, invoke: (api, r) => api.sessions.history(r) },
+  'session.models': { schema: sessionModelsRequestSchema, invoke: (api, r) => api.sessions.models(r) },
+  'session.selectModel': { schema: sessionSelectModelRequestSchema, invoke: (api, r) => api.sessions.selectModel(r) },
   'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },

packages/host/apiproxy/src/index.ts

@@ -45,7 +45,7 @@ export interface Config {
  * project directory and the fallback parent for name-created Workspaces.
  */
 export class ApiProxyService extends Service implements ApiProxy {
-  static inject = ['agents', 'sessions', 'tools', 'userInteraction', 'workspace']
+  static inject = ['agents', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
 
   static Config: z<Config> = z.object({
     provider: z.string().required(),

packages/host/apiproxy/tests/api-proxy-models.spec.ts

@@ -0,0 +1,233 @@
+/**
+ * Web session model-directory and selection behavior: dynamic provider grouping,
+ * provider-local catalog failures, logged-target restoration, advisory unlisted
+ * models, and the prompt-assembly boundary for a running selection change.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import LlmService, { LlmAdapter, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import type {
+  GenerateOptions, LlmCallConfig, LlmModelInfo, LlmModelReasoningInfo, LlmProviderInfo,
+  LlmResolvedModelInfo, StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`models-${String(nextRpc++)}`), payload }
+}
+
+class CatalogAdapter extends LlmAdapter {
+  constructor(
+    private readonly name: string,
+    private readonly models: readonly LlmModelInfo[] | Error,
+    private readonly reasoning?: LlmModelReasoningInfo,
+    private readonly exactError?: Error,
+  ) {
+    super()
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: this.name }
+  }
+
+  override listModels(): Promise<readonly LlmModelInfo[]> {
+    return this.models instanceof Error
+      ? Promise.reject(this.models)
+      : Promise.resolve(this.models)
+  }
+
+  override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+    if (this.exactError !== undefined) return Promise.reject(this.exactError)
+    return Promise.resolve({
+      provider,
+      id: model,
+      name: model,
+      ...this.reasoning === undefined ? {} : { reasoning: this.reasoning },
+    })
+  }
+
+  override async *stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // Catalog tests never enter provider streaming.
+  }
+}
+
+const REASONING: LlmModelReasoningInfo = {
+  efforts: [
+    { id: ReasoningEffortId('off'), name: 'Off' },
+    { id: ReasoningEffortId('high'), name: 'High' },
+    { id: ReasoningEffortId('max'), name: 'Max' },
+  ],
+  defaultEffort: ReasoningEffortId('high'),
+}
+
+async function harness(logged?: {
+  provider: string
+  model: string
+  reasoningEffort?: ReasoningEffortId
+}): Promise<{
+  ctx: Context
+  agent: Agent
+  sessionId: SessionId
+}> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(LlmService)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  ctx.llm.registerAdapter(['deepseek'], new CatalogAdapter('DeepSeek', [
+    { provider: 'deepseek', id: 'deepseek-chat', name: 'DeepSeek Chat' },
+    { provider: 'deepseek', id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
+  ], REASONING))
+  ctx.llm.registerAdapter(['broken'], new CatalogAdapter('Broken Provider', new Error('catalog offline')))
+  ctx.llm.registerAdapter(['metadata-broken'], new CatalogAdapter('Metadata Broken', [
+    { provider: 'metadata-broken', id: 'listed', name: 'Listed' },
+  ], undefined, new Error('reasoning metadata offline')))
+  ctx.llm.registerAdapter(['empty'], new CatalogAdapter('Empty Provider', []))
+  ctx.llm.registerAdapter(['duplicate'], new CatalogAdapter('Duplicate Provider', [
+    { provider: 'duplicate', id: 'same', name: 'Same' },
+    { provider: 'duplicate', id: 'same', name: 'Same Again' },
+  ]))
+  const session = ctx.sessions.create()
+  if (logged !== undefined) {
+    session.append('request/header', { header: { config: logged }, reason: 'initial' })
+  }
+  const agent = {
+    id: session.id,
+    session,
+    status: 'running',
+    ctx,
+  } as Agent
+  ctx.agents.register(agent)
+  return { ctx, agent, sessionId: session.id }
+}
+
+function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false } }): T {
+  if (!response.result.ok) throw new Error('expected successful response')
+  return response.result.value
+}
+
+describe('Web session model selection', () => {
+  it('groups successful providers, isolates failures, and preserves an unlisted current model', async () => {
+    const { ctx, sessionId } = await harness({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: ReasoningEffortId('max'),
+    })
+    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    expect(catalog.current).toEqual({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })
+    expect(catalog.groups).toEqual([{
+      id: 'deepseek',
+      name: 'DeepSeek',
+      models: [
+        { id: 'deepseek-chat', name: 'DeepSeek Chat', reasoning: REASONING },
+        {
+          id: 'deepseek-reasoner',
+          name: 'DeepSeek Reasoner',
+          description: 'Reasoning model',
+          reasoning: REASONING,
+        },
+        {
+          id: 'private-preview',
+          name: 'private-preview',
+          unlisted: true,
+          reasoning: REASONING,
+        },
+      ],
+    }])
+    expect(catalog.failures).toEqual([
+      { id: 'broken', name: 'Broken Provider', message: 'catalog offline' },
+      { id: 'metadata-broken', name: 'Metadata Broken', message: 'reasoning metadata offline' },
+      {
+        id: 'duplicate',
+        name: 'Duplicate Provider',
+        message: 'adapter returned invalid or duplicate model metadata for provider "duplicate"',
+      },
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
+    const { ctx, agent, sessionId } = await harness()
+    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
+    const signal = new AbortController().signal
+
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek', model: 'deepseek-chat' })
+    expect((await ctx.systemPrompt.assemble()).variables)
+      .toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+
+    const selected = expectValue(await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })))
+    expect(selected.selected).toEqual({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, signal, () => Promise.resolve(seed),
+    )).resolves.toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+
+    expect((await ctx.systemPrompt.assemble()).variables)
+      .toMatchObject({ provider: 'deepseek', model: 'private-preview' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 1, signal, () => Promise.resolve(seed),
+    )).resolves.toMatchObject({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })
+
+    const unsupported = await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'medium',
+    }))
+    expect(unsupported.result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'model-unavailable',
+        message: 'provider "deepseek" model "private-preview" does not support reasoning effort "medium"',
+      },
+    })
+
+    const rejected = await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'missing',
+      model: 'model',
+    }))
+    expect(rejected.result).toEqual({
+      ok: false,
+      error: {
+        code: 'model-unavailable',
+        message: 'no adapter registered for provider "missing"',
+        details: { provider: 'missing', model: 'model' },
+      },
+    })
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek', model: 'private-preview', reasoningEffort: 'max' })
+    await ctx.fiber.dispose()
+  })
+})

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -30,7 +30,19 @@ function scriptedApi(overrides: {
     sessions: {
       list: r => ok(r, { items: [] }),
       create: r => ok(r, { sessionId: sid('s-new') }),
-      history: r => ok(r, { events: [], hasMore: false }),
+      history: r => ok(r, {
+        events: [],
+        hasMore: false,
+        modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      }),
+      models: r => ok(r, {
+        current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        groups: [],
+        failures: [],
+      }),
+      selectModel: r => ok(r, {
+        selected: { provider: r.payload.provider, model: r.payload.model },
+      }),
       prompt: r => ok(r, { accepted: true as const }),
       cancel: r => ok(r, { accepted: true as const }),
       ...overrides.sessions,

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -36,6 +36,36 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           result: { ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: request.payload.sessionId } } },
         }
       },
+      async models(request) {
+        return {
+          rpcId: request.rpcId,
+          result: {
+            ok: true,
+            value: {
+              current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+              groups: [],
+              failures: [],
+            },
+          },
+        }
+      },
+      async selectModel(request) {
+        return {
+          rpcId: request.rpcId,
+          result: {
+            ok: true,
+            value: {
+              selected: {
+                provider: request.payload.provider,
+                model: request.payload.model,
+                ...request.payload.reasoningEffort === undefined
+                  ? {}
+                  : { reasoningEffort: request.payload.reasoningEffort },
+              },
+            },
+          },
+        }
+      },
       async prompt(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
@@ -143,6 +173,23 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
   it('covers create/prompt/cancel/describe passthrough', async () => {
     const c = client()
     expect((await c.sessions.create({})).result.ok).toBe(true)
+    expect((await c.sessions.models({ sessionId: 's' as never })).result.ok).toBe(true)
+    const selected = await c.sessions.selectModel({
+      sessionId: 's' as never,
+      provider: 'deepseek',
+      model: 'deepseek-v4-flash',
+      reasoningEffort: 'max',
+    })
+    expect(selected.result).toMatchObject({
+      ok: true,
+      value: {
+        selected: {
+          provider: 'deepseek',
+          model: 'deepseek-v4-flash',
+          reasoningEffort: 'max',
+        },
+      },
+    })
     expect((await c.sessions.prompt({ sessionId: 's' as never, mode: 'queue', content: [{ type: 'text', text: 'x' }] })).result.ok).toBe(true)
     expect((await c.sessions.cancel({ sessionId: 's' as never })).result.ok).toBe(true)
     expect((await c.host.describe({})).result.ok).toBe(true)

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -8,8 +8,9 @@ import { z } from 'zod'
 import {
   contentBlockSchema, sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
   sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
-  sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionPromptRequestSchema,
-  sessionPromptValueSchema, sessionSummarySchema,
+  sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionModelsRequestSchema,
+  sessionModelsValueSchema, sessionPromptRequestSchema, sessionPromptValueSchema,
+  sessionSelectModelRequestSchema, sessionSelectModelValueSchema, sessionSummarySchema,
 } from '../src/api/sessions.schema.ts'
 import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
 import {
@@ -56,6 +57,11 @@ describe('rpcErrorSchema', () => {
     expect(rpcErrorSchema.parse({ code: 'workspace-invalid-path', message: 'm', details: { path: '/x' } }).code).toBe('workspace-invalid-path')
     expect(rpcErrorSchema.parse({ code: 'workspace-name-conflict', message: 'm', details: { name: 'x' } }).code).toBe('workspace-name-conflict')
     expect(rpcErrorSchema.parse({ code: 'workspace-move-invalid', message: 'm', details: { workspaceId: 'w', sessionId: 's' } }).code).toBe('workspace-move-invalid')
+    expect(rpcErrorSchema.parse({
+      code: 'model-unavailable',
+      message: 'm',
+      details: { provider: 'p', model: 'm' },
+    }).code).toBe('model-unavailable')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
   })
@@ -129,7 +135,62 @@ describe('sessions domain schemas', () => {
     expect(sessionCreateValueSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionHistoryRequestSchema.parse({ sessionId: 's1', beforeSeq: 3, maxMessages: 5 }).beforeSeq).toBe(3)
     expect(() => sessionHistoryRequestSchema.parse({ sessionId: 's1', maxMessages: 0 })).toThrow()
-    expect(sessionHistoryValueSchema.parse({ events: [], hasMore: false }).hasMore).toBe(false)
+    expect(sessionHistoryValueSchema.parse({
+      events: [],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    }).hasMore).toBe(false)
+    expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionModelsValueSchema.parse({
+      current: { provider: 'deepseek', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
+      groups: [{
+        id: 'deepseek',
+        name: 'DeepSeek',
+        models: [{
+          id: 'deepseek-v4-flash',
+          name: 'DeepSeek V4 Flash',
+          description: 'fast',
+          unlisted: true,
+          reasoning: {
+            efforts: [
+              { id: 'off', name: 'Off' },
+              { id: 'max', name: 'Max', description: 'Largest budget' },
+            ],
+            defaultEffort: 'off',
+          },
+        }],
+      }],
+      failures: [{ id: 'broken', name: 'Broken', message: 'offline' }],
+    }).groups[0]?.models[0]?.id).toBe('deepseek-v4-flash')
+    expect(sessionSelectModelRequestSchema.parse({
+      sessionId: 's1',
+      provider: 'deepseek',
+      model: 'deepseek-v4-pro',
+      reasoningEffort: 'max',
+    }).reasoningEffort).toBe('max')
+    expect(sessionSelectModelValueSchema.parse({
+      selected: { provider: 'deepseek', model: 'deepseek-v4-pro', reasoningEffort: 'max' },
+    }).selected.reasoningEffort).toBe('max')
+    expect(() => sessionSelectModelRequestSchema.parse({
+      sessionId: 's1',
+      provider: '',
+      model: 'm',
+    })).toThrow()
+    expect(() => sessionSelectModelRequestSchema.parse({
+      sessionId: 's1',
+      provider: 'deepseek',
+      model: 'm',
+      reasoningEffort: '',
+    })).toThrow()
+    expect(() => sessionModelsValueSchema.parse({
+      current: { provider: 'deepseek', model: 'm' },
+      groups: [{
+        id: 'deepseek',
+        name: 'DeepSeek',
+        models: [{ id: 'm', name: 'M', reasoning: { efforts: [] } }],
+      }],
+      failures: [],
+    })).toThrow()
     const prompt = sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'queue', content: [{ type: 'text', text: 'hi' }] })
     expect(prompt.mode).toBe('queue')
     expect(() => sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'inject', content: [] })).toThrow()

packages/llm/llm-deepseek/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-deepseek/README.md
-README.md: a7f2fcb9c21d45a95fc81abd3dc1424d4336966d
-README.zh.md: bca56e700c0067b644adb4d1460a47901db28209
+README.md: 7a2314ea2ca0fb6606310a4961fcbc658240a7b8
+README.zh.md: 523bbbfd29b4598c024a1fff4a7121a7cb88bf41

packages/llm/llm-deepseek/README.md

@@ -28,13 +28,13 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
     defaultContextWindow: 256000 # optional positive-integer fallback for models without an exact value
     models:                  # optional; defaults to V4 Flash and V4 Pro
       - id: deepseek-v4-flash
-        name: DeepSeek V4 Flash
+        name: DeepSeek-V4-Flash
       - id: private-reasoner
         description: Company-hosted reasoning model
         contextWindow: 64000
 ```
 
-The plugin registers the single provider route `deepseek` together with its resolved `retryPolicy`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`, each with a 128,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for UI selectors and deployment introspection, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
+The plugin registers the single provider route `deepseek` together with its resolved `retryPolicy`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` as `DeepSeek-V4-Flash` and `deepseek-v4-pro` as `DeepSeek-V4-Pro`, each with a 256,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for clients such as ACP editors and the Web selector, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
 
 `contextWindow` is optional per configured model and is not exposed through the advisory catalog. `ctx.llm.resolveModelInfo('deepseek', model).context` returns an exact model value first, then `defaultContextWindow` for an entry without capacity or an unlisted pass-through id. When neither value exists, `context` is absent without invalidating routing. Pressure-sensitive plugins therefore get deployment-owned capacity without treating the model selector as authoritative. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
 

packages/llm/llm-deepseek/README.zh.md

@@ -28,13 +28,13 @@ harness LLM seam 的 DeepSeek chat-completions 适配器：直接 `fetch` + SSE
     defaultContextWindow: 256000 # optional positive-integer fallback for models without an exact value
     models:                  # optional; defaults to V4 Flash and V4 Pro
       - id: deepseek-v4-flash
-        name: DeepSeek V4 Flash
+        name: DeepSeek-V4-Flash
       - id: private-reasoner
         description: Company-hosted reasoning model
         contextWindow: 64000
 ```
 
-该插件注册唯一提供方路由 `deepseek`，同时注册解析后的 `retryPolicy`。请求使用 `provider: deepseek` 选择该路由；其 `model` 会作为协议 `model` 字符串原样传递，因此更改 DeepSeek 模型不需要生命周期时注册。省略 `models` 会公布 `deepseek-v4-flash` 和 `deepseek-v4-pro`，两者的上下文窗口均为 128,000 token；显式列表会替换这些默认值，`models: []` 则不公布任何模型。Catalog 配置项通过 `ctx.llm.listModels('deepseek')` 公开给 UI selector 与部署自省，但仍只提供建议：未列出模型 id 仍原样传递。省略配置项 name 默认为其 id。
+该插件注册唯一提供方路由 `deepseek`，同时注册解析后的 `retryPolicy`。请求使用 `provider: deepseek` 选择该路由；其 `model` 会作为协议 `model` 字符串原样传递，因此更改 DeepSeek 模型不需要生命周期时注册。省略 `models` 会公布 `deepseek-v4-flash`（名称为 `DeepSeek-V4-Flash`）和 `deepseek-v4-pro`（名称为 `DeepSeek-V4-Pro`），两者的上下文窗口均为 256,000 token；显式列表会替换这些默认值，`models: []` 则不公布任何模型。Catalog 配置项通过 `ctx.llm.listModels('deepseek')` 公开给 ACP（Agent Client Protocol）编辑器和 Web 选择器等客户端，但仍只提供建议：未列出模型 id 仍原样传递。省略配置项 name 默认为其 id。
 
 `contextWindow` 对每个已配置模型都可选，不会通过建议 catalog 公开。`ctx.llm.resolveModelInfo('deepseek', model).context` 先返回精确模型值，再对不含容量的配置项或未列出原样传递 id 返回 `defaultContextWindow`。两者都不存在时，`context` 字段缺失但不会使路由失效。因此，压力敏感插件可以获得部署拥有的容量，不会将模型 selector 视为权威。为 `deepseek` 注册另一个适配器会抛出 `LlmError('DUPLICATE_ADAPTER')`。
 

packages/llm/llm-deepseek/src/index.ts

@@ -22,8 +22,8 @@ export const name = 'llm-deepseek'
 export const inject = ['llm']
 
 const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
-  { id: 'deepseek-v4-flash', contextWindow: 128_000 },
-  { id: 'deepseek-v4-pro', contextWindow: 128_000 },
+  { id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', contextWindow: 256_000 },
+  { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro', contextWindow: 256_000 },
 ]
 
 /**

packages/llm/llm-deepseek/tests/adapter.spec.ts

@@ -628,15 +628,15 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmDeepSeek, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
     expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
     await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
-      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
-      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' },
     ])
     await expect(ctx.llm.resolveModelInfo('deepseek', 'deepseek-v4-flash'))
       .resolves.toMatchObject({
         provider: 'deepseek',
         id: 'deepseek-v4-flash',
-        name: 'deepseek-v4-flash',
-        context: { contextWindow: 128_000 },
+        name: 'DeepSeek-V4-Flash',
+        context: { contextWindow: 256_000 },
         reasoning: {
           efforts: [
             { id: ReasoningEffortId('off'), name: 'Off' },
@@ -732,8 +732,8 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
     LlmDeepSeek.apply(ctx, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
     await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
-      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
-      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' },
     ])
   })
 

packages/sdk/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 53995820a575d68bbd3322f82e21fa6d3456b38e
-README.zh.md: d3481cab032a9bede9b85ce0f4010566592befbd
+README.md: 0dcf3655fc4d20452981f83000f9b9b586ede17b
+README.zh.md: 1a692de2f7dc56cc3dbc7e40b8e2369d0bf2e8c5

packages/sdk/README.md

@@ -2,15 +2,17 @@
 
 English | [中文](README.zh.md)
 
-Developer tooling for creating, editing, building, and running DeepSeek Harness projects.
+Developer tooling for creating, editing, building, and running DeepSeek Harness projects, plus the client SDK stack for driving a harness runtime from another process.
 
-The [feature Agent Note](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md) owns the developer workflow; the [architecture Agent Note](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the package and project-editing boundaries.
+The [feature Agent Note](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md) owns the developer workflow; the [architecture Agent Note](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the package and project-editing boundaries; the [TypeScript SDK Agent Note](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md) owns the client SDK stack.
 
 | Package | Role |
 |---|---|
 | [`helper`](helper/README.md) | Project aggregate, edit session, builtin features, project documents, templates, package managers, and prompt abstraction |
 | [`scripts`](scripts/README.md) | The `dsh-sdk` launcher: `start`, `dev`, `build`, and interactive `config` |
 | [`create-sdk`](create-sdk/README.md) | The `npm create @deepseek-ai/sdk` initializer |
+| [`sdk-protocol`](sdk-protocol/README.md) | Shared SDK runtime wire protocol: the newline-delimited JSON-RPC transport + named request/notification types |
+| [`sdk-client`](sdk-client/README.md) | TypeScript client SDK: drive a harness runtime subprocess over stdio JSON-RPC (the Python SDK's design twin) |
 
 `@deepseek-ai/create-sdk` is the one package-name exception to the repository's `@deepseek-ai/dsh-*` rule: npm's scoped initializer convention requires that name for `npm create @deepseek-ai/sdk`.
 

packages/sdk/README.zh.md

@@ -2,15 +2,17 @@
 
 [English](README.md) | 中文
 
-用于创建、编辑、构建和运行 DeepSeek Harness 项目的开发者工具。
+用于创建、编辑、构建和运行 DeepSeek Harness 项目的开发者工具，外加从另一进程驱动 harness 运行时的客户端 SDK 栈。
 
-[功能 Agent Note](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)负责开发者工作流；[架构 Agent Note](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)负责包与项目编辑边界。
+[功能 Agent Note](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)负责开发者工作流；[架构 Agent Note](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)负责包与项目编辑边界；[TypeScript SDK Agent Note](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)负责客户端 SDK 栈。
 
 | 包 | 职责 |
 |---|---|
 | [`helper`](helper/README.md) | 项目聚合、编辑会话、内置功能、项目文档、模板、包管理器与提示词抽象 |
 | [`scripts`](scripts/README.md) | `dsh-sdk` 启动器：`start`、`dev`、`build` 和交互式 `config` |
 | [`create-sdk`](create-sdk/README.md) | `npm create @deepseek-ai/sdk` 初始化器 |
+| [`sdk-protocol`](sdk-protocol/README.md) | 共享的 SDK 运行时线协议：按换行分帧的 JSON-RPC 传输 + 具名请求/通知类型 |
+| [`sdk-client`](sdk-client/README.md) | TypeScript 客户端 SDK：走 stdio JSON-RPC 驱动 harness 运行时子进程（Python SDK 的设计孪生） |
 
 `@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外：npm 的 scoped initializer 约定要求使用该名称，才能支持 `npm create @deepseek-ai/sdk`。
 

packages/sdk/sdk-client/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/sdk/sdk-client/README.md
+README.md: e2aaf08212307bfac0c73b5e838679a7a750a92a
+README.zh.md: cbefae59d95cc0cb9d89145ad3f2ee3248822714

packages/sdk/sdk-client/README.md

@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-sdk-client
+
+English | [中文](README.zh.md)
+
+The TypeScript client SDK for driving a DeepSeek Harness runtime as a subprocess over stdio JSON-RPC — the design twin of the [Python SDK](../../../python/README.md) (`deepseek-harness`), sharing the same runtime peer, protocol, and layering: `DeepSeekHarness` is the high-level turns API, `HarnessClient` the lower-level protocol client. A pure library: it registers nothing on a Cordis context; the runtime process it spawns is a complete harness whose composition its own `cordis.yml` decides.
+
+Unlike the Python SDK, the launch spec is fully explicit (`command`/`args`): this package is for repo-adjacent TypeScript consumers — the [`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.md) backend, tests, automation — which know which runtime they are launching. Bundled-runtime resolution (finding a packaged executable) remains the Python distribution's concern.
+
+## DeepSeekHarness
+
+```ts
+import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'
+
+await using harness = new DeepSeekHarness({
+  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
+  provider: 'deepseek',
+  model: 'deepseek-v4-flash',
+})
+const result = await harness.run('say hi')
+console.log(result.status, result.finalResponse)
+```
+
+The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; `close()` (or `await using`) is required so the child is always reaped. `start()` memoizes the `initialize` handshake (the workspace cwd — resolved absolute before it crosses the wire — plus the provider/model route); a failed handshake reaps the runtime and swaps in a fresh client, so a later call retries with a new subprocess (until `close()`, which is terminal). `session(id?)` opens a named or fresh session handle; `run(input, { sessionId?, onNotification? })` sends one prompt turn and settles when the paired `session.finished` arrives, returning a `TurnResult`: `status` (`ok`/`error` as the deployment maps it), the structured `reason` (`TurnEndReason`), `finalResponse` (last assistant message text), plus every `session.event` envelope and raw notification observed for that session tree, in wire order. Model-level failure is a `status: 'error'` result, never a rejection; rejections mean transport loss, timeout, or protocol violation.
+
+## HarnessClient
+
+The protocol client under the turns API: explicit `start()`/`initialize()`/`prompt()`/`request()`/`close()`, plus notification subscriptions. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK. Error surfaces are typed: `JsonRpcResponseError` (wire error response, code/data preserved), `RequestTimeoutError` (a configured bound elapsed; there is no wire-level cancel, so the request keeps running server-side until close), `SdkProtocolError` (a response outside the documented protocol), `TransportClosedError` (the runtime is gone — message carries the exit code and a bounded stderr tail).
+
+`close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder (`disposeEofGraceMs` default 6000, `disposeGraceMs` default 3000) until the process has actually exited. The ladder is private to this client: it runs outside any harness context, so it cannot ride the [`dsh-subprocess`](../../subprocess/README.md) service — the seam's documented exception for SDK-managed transports. It is idempotent, and a closed client refuses reuse.
+
+`HarnessClientOptions.env` replaces the child environment entirely when given (`undefined` inherits the parent's); callers own credential policy — `scrubbedParentEnv` from `dsh-subprocess` is the shared scrub base for isolation-minded launches.
+
+## Testing
+
+Keyless unit tests drive a scripted fake runtime subprocess (`tests/fake-runtime.ts`, protocol-only, env-scripted) over real stdio: turn loop, session-tree scoping, timeout/death/malformed-response surfaces, and the dispose ladder. The [SDK snapshot suite](../../../examples/jsonrpc-agent/tests/sdk.snapshot.ts) drives the real `dsh-jsonrpc-agent` runtime through this client keylessly via `llm-replay`, pinning the notification stream, the turn result, and the persisted logs; `DSH_SNAPSHOT=record` re-records against the live API.
+
+## Model Experience
+
+None, as this is a client-process library; the model runs in the spawned runtime, whose experience is owned by the plugins its `cordis.yml` composes.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No bundled-runtime resolution** — callers name the runtime executable explicitly; packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists.
+- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../sdk-protocol/README.md)).
+- **One in-flight prompt per session** — a server-side rule this client surfaces as a `JsonRpcResponseError`; independent sessions run concurrently on one runtime.
+- **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows.

packages/sdk/sdk-client/README.zh.md

@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-sdk-client
+
+[English](README.md) | 中文
+
+以子进程方式驱动 DeepSeek Harness 运行时、走 stdio JSON-RPC 的 TypeScript 客户端 SDK——[Python SDK](../../../python/README.md)（`deepseek-harness`）的设计孪生，共享同一个运行时对端、协议与分层：`DeepSeekHarness` 是高层回合 API，`HarnessClient` 是低层协议客户端。纯库：不在任何 Cordis 上下文注册；它所生成的运行时进程是一个完整 harness，其组成由自己的 `cordis.yml` 决定。
+
+与 Python SDK 不同，启动规格完全显式（`command`/`args`）：本包面向仓库近旁的 TypeScript 消费者——[`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.md) 后端、测试、自动化——它们知道自己要启动哪个运行时。捆绑运行时解析（寻找打包可执行文件）仍归 Python 发行版负责。
+
+## DeepSeekHarness
+
+```ts
+import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'
+
+await using harness = new DeepSeekHarness({
+  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
+  provider: 'deepseek',
+  model: 'deepseek-v4-flash',
+})
+const result = await harness.run('say hi')
+console.log(result.status, result.finalResponse)
+```
+
+子进程在首次使用时惰性启动，并在多次 `run()` 之间持续归实例所有；必须 `close()`（或 `await using`），子进程才总能被收割。`start()` 记忆化 `initialize` 握手（工作区 cwd——在跨越线之前解析为绝对路径——加 provider/model 路由）；握手失败会收割运行时并换入全新客户端，后续调用用新子进程重试（直到终结性的 `close()`）。`session(id?)` 打开具名或全新的会话句柄；`run(input, { sessionId?, onNotification? })` 发送一个 prompt 回合，在配对的 `session.finished` 到达时尘埃落定，返回 `TurnResult`：`status`（按部署映射的 `ok`/`error`）、结构化 `reason`（`TurnEndReason`）、`finalResponse`（最后一条助手消息文本），以及该会话树内按线序观察到的全部 `session.event` 封套与原始通知。模型层失败是 `status: 'error'` 的结果，绝不是拒绝；拒绝意味着传输丢失、超时或协议违例。
+
+## HarnessClient
+
+回合 API 之下的协议客户端：显式 `start()`/`initialize()`/`prompt()`/`request()`/`close()`，外加通知订阅。`subscribe(filter?)` 返回 `NotificationSubscription`（可等待的 `next()`、非阻塞 `tryNext()`、异步迭代）；`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知，范围限定在客户端完成，与 Python SDK 完全一致。错误表面有类型：`JsonRpcResponseError`（线上错误响应，保留 code/data）、`RequestTimeoutError`（配置的时限已到；线上没有取消方法，请求在服务端继续运行直到 close）、`SdkProtocolError`（响应超出文档化协议）、`TransportClosedError`（运行时已消失——消息携带退出码与有界 stderr 尾部）。
+
+`close()` 先请求协议 `shutdown`（受 `shutdownTimeoutMs` 约束，默认 1000 毫秒），然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯（`disposeEofGraceMs` 默认 6000，`disposeGraceMs` 默认 3000）直到进程真正退出。该阶梯为本客户端私有：它运行在任何 harness 上下文之外，无法搭乘 [`dsh-subprocess`](../../subprocess/README.md) 服务——即该接缝记载的 SDK 托管传输例外。幂等，已关闭的客户端拒绝复用。
+
+`HarnessClientOptions.env` 给定时整体替换子环境（`undefined` 原样继承父环境）；凭据策略归调用方——`dsh-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。
+
+## 测试
+
+免密钥单元测试通过真实 stdio 驱动一个脚本化伪运行时子进程（`tests/fake-runtime.ts`，纯协议、环境变量脚本化）：回合循环、会话树范围限定、超时/死亡/畸形响应表面、处置阶梯。[SDK 快照套件](../../../examples/jsonrpc-agent/tests/sdk.snapshot.ts)经由 `llm-replay` 免密钥地通过本客户端驱动真实 `dsh-jsonrpc-agent` 运行时，钉住通知流、回合结果与持久化日志；`DSH_SNAPSHOT=record` 对真实 API 重录。
+
+## Model Experience
+
+None, as this is a client-process library; the model runs in the spawned runtime, whose experience is owned by the plugins its `cordis.yml` composes.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **无捆绑运行时解析** —— 调用方显式指定运行时可执行文件；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费者。
+- **无回合中取消** —— 线上没有 prompt 取消方法；放弃回合意味着关闭运行时（见协议的 [Known Limitations](../sdk-protocol/README.md)）。
+- **每会话同时只有一个在途 prompt** —— 服务端规则，本客户端将其呈现为 `JsonRpcResponseError`；相互独立的会话可在同一运行时上并发。
+- **client→server 通知与 server→client 请求**在线两端都未实现；传输层为未来审批流保留了承载能力。

packages/sdk/sdk-client/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@deepseek-ai/dsh-sdk-client",
+  "description": "TypeScript client SDK for driving a DeepSeek Harness runtime subprocess over stdio JSON-RPC: the DeepSeekHarness high-level turns API and the lower-level HarnessClient",
+  "version": "0.0.1",
+  "private": true,
+  "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",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-sdk-protocol": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/sdk/sdk-client/src/api.ts

@@ -0,0 +1,251 @@
+/**
+ * High-level turns API over {@link HarnessClient}: `DeepSeekHarness` owns one
+ * runtime subprocess across many sessions; `HarnessSession.run` sends a
+ * prompt and settles with the final response once `session.finished` arrives.
+ * Mirrors the Python SDK's `DeepSeekHarness`/`Session` pair.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/api
+ */
+
+import { randomUUID } from 'node:crypto'
+import { resolve } from 'node:path'
+import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
+import { HarnessClient, isRecord, SdkProtocolError } from './client.ts'
+import type { ContentBlock, DeepSeekHarnessOptions, HarnessClientOptions, HarnessNotification, TurnResult } from './types.ts'
+
+/**
+ * Reusable SDK for running DeepSeek Harness agent turns in a runtime
+ * subprocess. The subprocess starts lazily on first use and stays owned by
+ * this instance until {@link close}; always close (or `await using`) so the
+ * child is reaped.
+ */
+export class DeepSeekHarness implements AsyncDisposable {
+  private clientInstance: HarnessClient
+  private readonly launch: HarnessClientOptions
+  private readonly cwd: string
+  private readonly provider: string
+  private readonly model: string
+  private initialized: Promise<void> | undefined
+  private closed = false
+
+  /** @param options - runtime launch spec plus the session route (cwd/provider/model). */
+  constructor(options: DeepSeekHarnessOptions) {
+    this.launch = options.launch
+    this.clientInstance = new HarnessClient(options.launch)
+    // Absolute before the handshake: the child spawns relative to THIS
+    // process's cwd, but the wire cwd is resolved again inside the child — a
+    // relative value would double-resolve (e.g. `worker` → `worker/worker`).
+    this.cwd = resolve(options.cwd ?? options.launch.cwd ?? process.cwd())
+    this.provider = options.provider ?? 'deepseek'
+    this.model = options.model ?? 'deepseek-v4-flash'
+  }
+
+  /**
+   * The underlying JSON-RPC client (exposed for low-level access). A failed
+   * handshake reaps its runtime and swaps in a fresh instance, so do not
+   * cache this across a failed {@link start}.
+   * @returns the client currently owning the runtime subprocess.
+   */
+  get client(): HarnessClient {
+    return this.clientInstance
+  }
+
+  /**
+   * Start the subprocess and perform the `initialize` handshake once. On
+   * failure the runtime is reaped and a fresh client replaces it
+   * (`HarnessClient.close` is permanent), so a later call retries with a new
+   * subprocess — unless {@link close} already ended this harness.
+   * @returns settlement of the (memoized) handshake.
+   */
+  start(): Promise<void> {
+    this.initialized ??= (async () => {
+      try {
+        this.clientInstance.start()
+        await this.clientInstance.initialize({ cwd: this.cwd, provider: this.provider, model: this.model })
+      } catch (error) {
+        this.initialized = undefined
+        await this.clientInstance.close()
+        if (!this.closed) this.clientInstance = new HarnessClient(this.launch)
+        throw error
+      }
+    })()
+    return this.initialized
+  }
+
+  /**
+   * Open a session handle (no wire traffic; the runtime creates the session
+   * on its first prompt).
+   * @param sessionId - explicit id to reuse; omitted mints a fresh one.
+   * @returns the session handle.
+   */
+  session(sessionId?: string): HarnessSession {
+    return new HarnessSession(this, sessionId ?? `session-${randomUUID().replaceAll('-', '')}`)
+  }
+
+  /**
+   * Run one prompt on a fresh (or named) session.
+   * @param input - prompt text, or content blocks sent verbatim.
+   * @param options - optional session id and per-notification observer.
+   * @returns the settled turn result.
+   */
+  run(input: string | ContentBlock[], options?: RunOptions): Promise<TurnResult> {
+    return this.session(options?.sessionId).run(input, options)
+  }
+
+  /**
+   * Shut down and reap the runtime subprocess. Idempotent and terminal —
+   * a closed harness no longer retries a failed handshake.
+   * @returns settlement of the complete teardown.
+   */
+  close(): Promise<void> {
+    this.closed = true
+    return this.clientInstance.close()
+  }
+
+  /**
+   * `await using` support: {@link close}.
+   * @returns settlement of the teardown.
+   */
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
+  }
+}
+
+/** Per-run options: target session and streaming observer. */
+export interface RunOptions {
+  /** Session id to run on; omitted mints a fresh session per call. */
+  sessionId?: string
+  /** Observer invoked with every notification for this session tree, in wire order. */
+  onNotification?: (notification: HarnessNotification) => void
+}
+
+/**
+ * One SDK session: a stable id plus the turn loop that pairs a
+ * `session/prompt` with its `session.finished`.
+ */
+export class HarnessSession {
+  /**
+   * @param harness - the owning harness (supplies the client and handshake).
+   * @param id - the wire session id this handle runs on.
+   */
+  constructor(readonly harness: DeepSeekHarness, readonly id: string) {}
+
+  /**
+   * Run one prompt turn to settlement.
+   * @param input - prompt text, or content blocks sent verbatim.
+   * @param options - optional per-notification observer.
+   * @returns the settled turn result; rejects on transport loss, timeout, or
+   * a protocol error — never on a model-level failure (that is
+   * `status: 'error'` in the result).
+   */
+  async run(input: string | ContentBlock[], options?: Pick<RunOptions, 'onNotification'>): Promise<TurnResult> {
+    await this.harness.start()
+    const client = this.harness.client
+    const contentBlocks = normalizeInput(input)
+    const events: SessionEvent[] = []
+    const notifications: HarnessNotification[] = []
+    let status: TurnResult['status'] = 'error'
+    let reason: TurnEndReason | undefined
+    let finished = false
+
+    const subscription = client.subscribeSessionTree(this.id)
+    const collect = (notification: HarnessNotification): void => {
+      if (notification.method === 'session.event' && notification.params.sessionId === this.id) {
+        // Wire boundary: the envelope feeds the typed TurnResult, so a
+        // malformed runtime surfaces as a protocol error, not as type-invalid
+        // data (or a TypeError out of finalResponse).
+        const event = validatedSessionEvent(notification.params.event)
+        notifications.push(notification)
+        options?.onNotification?.(notification)
+        events.push(event)
+        return
+      }
+      if (notification.method === 'session.finished' && notification.params.sessionId === this.id) {
+        reason = validatedTurnEndReason(notification.params.reason)
+        notifications.push(notification)
+        options?.onNotification?.(notification)
+        status = notification.params.status === 'ok' ? 'ok' : 'error'
+        finished = true
+        return
+      }
+      notifications.push(notification)
+      options?.onNotification?.(notification)
+    }
+    const accepted = client.prompt(this.id, contentBlocks)
+    // Drain concurrently so observers see progress while the prompt request
+    // is still pending (its response arrives only after settlement).
+    const drain = (async () => {
+      while (!finished) collect(await subscription.next())
+    })()
+    try {
+      await Promise.all([accepted, drain])
+    } finally {
+      // On a prompt rejection the drain is still parked on next(); closing the
+      // subscription settles it, and the swallow keeps that secondary
+      // TransportClosedError from surfacing as an unhandled rejection.
+      subscription.close()
+      await drain.catch(() => {})
+    }
+
+    return {
+      sessionId: this.id,
+      status,
+      reason,
+      finalResponse: finalResponse(events),
+      events,
+      notifications,
+    }
+  }
+}
+
+/**
+ * Normalize run input: a string becomes one text block; blocks pass verbatim.
+ * @param input - prompt text or content blocks.
+ * @returns the content blocks to send.
+ */
+export function normalizeInput(input: string | ContentBlock[]): ContentBlock[] {
+  return typeof input === 'string' ? [{ type: 'text', text: input }] : input
+}
+
+/** Validate a wire `session.event` envelope to the shape the typed result exposes. */
+function validatedSessionEvent(value: unknown): SessionEvent {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    throw new SdkProtocolError(`session.event carried no event envelope: ${JSON.stringify(value)}`)
+  }
+  // The one variant this module reads into (finalResponse) must carry
+  // kind-tagged content blocks; other variants pass through under their
+  // envelope shape.
+  if (value.type === 'assistant/message') {
+    const content = isRecord(value.data) ? value.data.content : undefined
+    if (!Array.isArray(content) || !content.every(block => isRecord(block) && typeof block.type === 'string')) {
+      throw new SdkProtocolError(`assistant/message event carried malformed content: ${JSON.stringify(value)}`)
+    }
+  }
+  return value as unknown as SessionEvent
+}
+
+/** Validate a wire `session.finished` reason (absent, or a kind-tagged record). */
+function validatedTurnEndReason(value: unknown): TurnEndReason | undefined {
+  if (value === undefined) return undefined
+  if (!isRecord(value) || typeof value.kind !== 'string') {
+    throw new SdkProtocolError(`session.finished carried a malformed reason: ${JSON.stringify(value)}`)
+  }
+  return value as unknown as TurnEndReason
+}
+
+/**
+ * Extract the concatenated text of the last assistant message.
+ * @param events - the turn's `session.event` payloads in wire order.
+ * @returns the final response text, or `''` when no assistant message exists.
+ */
+export function finalResponse(events: SessionEvent[]): string {
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index]
+    if (event?.type !== 'assistant/message') continue
+    return event.data.content
+      .filter((block): block is ContentBlock & { type: 'text' } => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+  }
+  return ''
+}

packages/sdk/sdk-client/src/client.ts

@@ -0,0 +1,455 @@
+/**
+ * Low-level JSON-RPC client for a DeepSeek Harness SDK runtime subprocess.
+ * {@link HarnessClient} owns the child process: it spawns the runtime, speaks
+ * the `@deepseek-ai/dsh-sdk-protocol` wire over the child's stdio, fans
+ * server notifications out to subscriptions, and tears the child down to
+ * quiescence through a private EOF → SIGTERM → SIGKILL ladder. The design
+ * twin is the Python SDK's `HarnessClient` (`python/sdk`); both drive the
+ * same runtime protocol. This client runs OUTSIDE any harness context, so it
+ * spawns directly rather than through the `dsh-subprocess` service — the
+ * seam's documented exception for SDK-managed transports.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/client
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process'
+import {
+  JsonRpcLineTransport,
+  JsonRpcResponseError,
+  type InitializeParams,
+  type InitializeResult,
+  type SessionPromptParams,
+} from '@deepseek-ai/dsh-sdk-protocol'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { disposeRuntimeProcess } from './dispose.ts'
+import type { HarnessClientOptions, HarnessNotification, NotificationFilter } from './types.ts'
+
+/** Retained stderr lines used to diagnose an unexpected runtime death. */
+const STDERR_TAIL_LIMIT = 400
+
+/** Grace for the runtime's stdio streams to settle after its exit edge. */
+const STREAM_SETTLE_MS = 100
+
+/**
+ * The runtime subprocess is gone or unusable: it exited, its stdio closed, or
+ * it was never launchable. The message carries the exit code and a stderr
+ * tail when available.
+ */
+export class TransportClosedError extends Error {
+  /** @param message - the failure description, including any stderr tail. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'TransportClosedError'
+  }
+}
+
+/** A request exceeded {@link HarnessClientOptions.requestTimeoutMs}. */
+export class RequestTimeoutError extends Error {
+  /** @param message - which method timed out. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'RequestTimeoutError'
+  }
+}
+
+/**
+ * The runtime answered outside its documented protocol (for example a
+ * `session/prompt` response without `accepted: true`).
+ */
+export class SdkProtocolError extends Error {
+  /** @param message - the protocol violation description. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'SdkProtocolError'
+  }
+}
+
+interface SubscriptionState {
+  readonly queue: HarnessNotification[]
+  readonly waiters: { resolve: (item: HarnessNotification) => void; reject: (error: Error) => void }[]
+  readonly filter: NotificationFilter | undefined
+  failure: Error | undefined
+}
+
+/**
+ * One client-side notification stream. Delivery order matches the wire;
+ * {@link close} detaches it from the client, after which {@link next} rejects.
+ */
+export class NotificationSubscription implements AsyncIterable<HarnessNotification> {
+  constructor(
+    private readonly state: SubscriptionState,
+    private readonly unsubscribe: () => void,
+  ) {}
+
+  /**
+   * Await the next matching notification.
+   * @returns the notification; after the runtime died, drains what was
+   * already delivered and then rejects; after {@link close}, rejects
+   * immediately (the queue is dropped).
+   */
+  next(): Promise<HarnessNotification> {
+    const queued = this.state.queue.shift()
+    if (queued !== undefined) return Promise.resolve(queued)
+    if (this.state.failure !== undefined) return Promise.reject(this.state.failure)
+    return new Promise((resolve, reject) => {
+      this.state.waiters.push({ resolve, reject })
+    })
+  }
+
+  /**
+   * Drain one already-delivered notification without waiting.
+   * @returns the next queued notification, or `undefined` when none is queued.
+   */
+  tryNext(): HarnessNotification | undefined {
+    return this.state.queue.shift()
+  }
+
+  /** Detach from the client; queued items drop and pending waiters reject. */
+  close(): void {
+    this.unsubscribe()
+    // The drop is part of this method's contract; a runtime-death fail() keeps
+    // the queue so already-delivered notifications remain drainable.
+    this.state.queue.length = 0
+    this.fail(new TransportClosedError('notification subscription closed'))
+  }
+
+  /**
+   * Reject pending and future waits (delivery stops; the first failure wins).
+   * Already-queued notifications remain drainable via {@link next}/{@link tryNext}.
+   * @param error - the terminal failure delivered to waiters.
+   */
+  fail(error: Error): void {
+    this.state.failure ??= error
+    for (const waiter of this.state.waiters.splice(0)) waiter.reject(this.state.failure)
+  }
+
+  /**
+   * Deliver one notification to a waiter or the queue when the filter
+   * matches. A throwing filter fails only THIS subscription (detached, the
+   * throw becomes its terminal error) — it never disturbs sibling
+   * subscriptions or the transport's read loop, mirroring the Python client.
+   * @param notification - the wire notification to deliver.
+   */
+  push(notification: HarnessNotification): void {
+    let matches: boolean
+    try {
+      matches = this.state.filter === undefined || this.state.filter(notification)
+    } catch (error) {
+      this.unsubscribe()
+      this.fail(error instanceof Error ? error : new Error(String(error)))
+      return
+    }
+    if (!matches) return
+    const waiter = this.state.waiters.shift()
+    if (waiter !== undefined) waiter.resolve(notification)
+    else this.state.queue.push(notification)
+  }
+
+  /**
+   * Iterate notifications until the subscription or runtime closes (the
+   * terminating rejection propagates).
+   * @returns an async iterator over {@link next} results.
+   */
+  async * [Symbol.asyncIterator](): AsyncIterator<HarnessNotification> {
+    for (;;) yield await this.next()
+  }
+}
+
+/**
+ * JSON-RPC client for the DeepSeek Harness SDK runtime over subprocess stdio.
+ *
+ * The subprocess starts lazily on {@link start} and is owned by this instance
+ * until {@link close}, which requests protocol `shutdown` and then walks the
+ * shared EOF → SIGTERM → SIGKILL dispose ladder to quiescence. There is no
+ * wire-level cancel: a timed-out request stays running server-side until the
+ * runtime is closed.
+ */
+export class HarnessClient {
+  private child: ChildProcess | undefined
+  private transport: JsonRpcLineTransport | undefined
+  private readonly stderrTail: string[] = []
+  private readonly subscriptions = new Map<string, NotificationSubscription>()
+  private readonly sessionParents = new Map<string, string>()
+  private subscriptionSerial = 0
+  private exitCode: number | null | undefined
+  private spawnError: Error | undefined
+  private streamsSettled: Promise<void> = Promise.resolve()
+  private closeTask: Promise<void> | undefined
+
+  /** @param options - launch spec, complete child environment, and timeouts. */
+  constructor(readonly options: HarnessClientOptions) {}
+
+  /**
+   * Spawn the runtime subprocess and start reading frames. Idempotent while
+   * the process is live; rejects reuse after {@link close}.
+   */
+  start(): void {
+    if (this.closeTask !== undefined) throw new TransportClosedError('DeepSeek Harness runtime client is closed')
+    if (this.child !== undefined) return
+    const child = spawn(this.options.command, this.options.args ?? [], {
+      cwd: this.options.cwd,
+      env: this.options.env ?? process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    this.child = child
+    child.once('error', (error) => {
+      this.spawnError = error
+      // A spawn failure destroys the pipes without an input 'end' edge, so the
+      // transport's pending requests must be failed here.
+      this.transport?.close()
+      this.failSubscriptions(this.closedError('DeepSeek Harness runtime failed to start'))
+    })
+    // Writes racing the runtime's death EPIPE on stdin; the exit edge below is
+    // the real signal, so the stream-level error only needs to be non-fatal.
+    // The timing of that race is not deterministically reproducible.
+    /* v8 ignore next */
+    child.stdin.on('error', () => {})
+    let stderrBuffer = ''
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => {
+      stderrBuffer += chunk
+      const newline = stderrBuffer.lastIndexOf('\n')
+      if (newline >= 0) {
+        this.appendStderr(stderrBuffer.slice(0, newline).split('\n'))
+        stderrBuffer = stderrBuffer.slice(newline + 1)
+      }
+    })
+    let signalStreamsSettled!: () => void
+    this.streamsSettled = new Promise((resolve) => { signalStreamsSettled = resolve })
+    const settled = { stderr: false, exited: false }
+    const maybeSettle = (): void => {
+      if (settled.stderr && settled.exited) signalStreamsSettled()
+    }
+    child.stderr.once('close', () => {
+      if (stderrBuffer.length > 0) this.appendStderr([stderrBuffer])
+      settled.stderr = true
+      maybeSettle()
+    })
+    child.once('exit', (code) => {
+      this.exitCode = code
+      settled.exited = true
+      maybeSettle()
+      this.failSubscriptions(this.closedError('DeepSeek Harness runtime exited'))
+    })
+    child.once('close', () => {
+      // All stdio has settled: stdout 'end' already drained every tail frame,
+      // so closing now cannot drop responses — it only fails requests that
+      // will never be answered.
+      this.transport?.close()
+    })
+    const transport = new JsonRpcLineTransport(child.stdout, child.stdin)
+    transport.onNotification((method, params) => { this.dispatchNotification({ method, params }) })
+    transport.start()
+    this.transport = transport
+  }
+
+  /**
+   * Perform the process-wide handshake.
+   * @param params - workspace cwd plus the provider/model route.
+   * @returns the runtime's wire identity.
+   */
+  async initialize(params: InitializeParams): Promise<InitializeResult> {
+    const result = await this.request('initialize', { ...params })
+    if (!isRecord(result) || !isRecord(result.serverInfo)
+      || typeof result.serverInfo.name !== 'string' || typeof result.serverInfo.version !== 'string') {
+      throw new SdkProtocolError(`initialize returned no server identity: ${JSON.stringify(result)}`)
+    }
+    return { serverInfo: { name: result.serverInfo.name, version: result.serverInfo.version } }
+  }
+
+  /**
+   * Run one prompt turn to settlement (the response arrives only after the
+   * turn settled; progress streams as notifications meanwhile).
+   * @param sessionId - target session; an unknown id creates it.
+   * @param contentBlocks - the user message, sent verbatim.
+   */
+  async prompt(sessionId: string, contentBlocks: ContentBlock[]): Promise<void> {
+    const params: SessionPromptParams = { sessionId, contentBlocks }
+    const result = await this.request('session/prompt', { ...params })
+    if (!isRecord(result) || result.accepted !== true) {
+      throw new SdkProtocolError(`session/prompt was not accepted: ${JSON.stringify(result)}`)
+    }
+  }
+
+  /**
+   * Send one JSON-RPC request and await its result.
+   * @param method - the wire method name.
+   * @param params - the params object; omitted params send `{}`.
+   * @param timeoutMs - per-call override of {@link HarnessClientOptions.requestTimeoutMs}.
+   * @returns the raw result; rejects with {@link JsonRpcResponseError} on a
+   * protocol error response, {@link RequestTimeoutError} on timeout, and
+   * {@link TransportClosedError} when the runtime is gone.
+   */
+  async request(method: string, params?: object, timeoutMs?: number): Promise<unknown> {
+    this.start()
+    // A dead runtime cannot answer; fail with process context instead of
+    // writing into a destroyed pipe and hanging until the timeout.
+    if (this.exitCode !== undefined || this.spawnError !== undefined) {
+      await this.settleStreams()
+      throw this.closedError('DeepSeek Harness runtime is not running')
+    }
+    const transport = this.transport
+    /* v8 ignore next -- start() either sets the transport or throws */
+    if (transport === undefined) throw new TransportClosedError('DeepSeek Harness runtime is not running')
+    const timeout = timeoutMs ?? this.options.requestTimeoutMs
+    try {
+      if (timeout === undefined) return await transport.request(method, params ?? {})
+      // The abort signal makes the timeout an abandonment: the transport drops
+      // its pending entry, so repeated bounded requests against a hung method
+      // retain no per-call state (the server-side work still runs to close).
+      const abandon = new AbortController()
+      const timer = setTimeout(() => {
+        abandon.abort(new RequestTimeoutError(`${method} timed out after ${timeout}ms waiting for the DeepSeek Harness runtime`))
+      }, timeout)
+      try {
+        return await transport.request(method, params ?? {}, abandon.signal)
+      } finally {
+        clearTimeout(timer)
+      }
+    } catch (error) {
+      if (error instanceof JsonRpcResponseError || error instanceof RequestTimeoutError) throw error
+      // Transport-level failures gain process context: exit code + stderr tail.
+      await this.settleStreams()
+      throw this.closedError(errorMessage(error))
+    }
+  }
+
+  /**
+   * Subscribe to server notifications.
+   * @param filter - optional predicate; omitted means every notification.
+   * @returns the subscription handle; close it to stop delivery. After
+   * {@link close} or runtime death the handle is born failed — there is no
+   * producer left, so `next()` rejects instead of waiting forever.
+   */
+  subscribe(filter?: NotificationFilter): NotificationSubscription {
+    const id = String(this.subscriptionSerial++)
+    const state: SubscriptionState = { queue: [], waiters: [], filter, failure: undefined }
+    const subscription = new NotificationSubscription(state, () => { this.subscriptions.delete(id) })
+    if (this.closeTask !== undefined || this.exitCode !== undefined || this.spawnError !== undefined) {
+      subscription.fail(this.closedError('DeepSeek Harness runtime closed'))
+      return subscription
+    }
+    this.subscriptions.set(id, subscription)
+    return subscription
+  }
+
+  /**
+   * Subscribe to one session and the descendants discovered from
+   * `subagent.started` lineage edges (the runtime notifies for every session
+   * in its context; scoping is client-side, mirroring the Python SDK).
+   * @param sessionId - the root session id.
+   * @returns the filtered subscription handle.
+   */
+  subscribeSessionTree(sessionId: string): NotificationSubscription {
+    return this.subscribe((notification) => {
+      const params = notification.params
+      if (notification.method === 'subagent.started' || notification.method === 'subagent.finished') {
+        const parentId = params.parentSessionId
+        if (typeof parentId === 'string' && this.isDescendantOf(parentId, sessionId)) return true
+        return params.childSessionId === sessionId
+      }
+      const relatedId = params.sessionId
+      return typeof relatedId === 'string' && this.isDescendantOf(relatedId, sessionId)
+    })
+  }
+
+  /**
+   * Shut the runtime down and reap it: a best-effort protocol `shutdown`
+   * bounded by `shutdownTimeoutMs`, then the shared stdin-EOF → SIGTERM →
+   * SIGKILL ladder until the process actually exited. Idempotent.
+   * @returns settlement of the complete teardown.
+   */
+  close(): Promise<void> {
+    this.closeTask ??= this.performClose()
+    return this.closeTask
+  }
+
+  private async performClose(): Promise<void> {
+    const child = this.child
+    if (child === undefined) return
+    try {
+      await this.request('shutdown', undefined, this.options.shutdownTimeoutMs ?? 1_000)
+    } catch (error) {
+      // Diagnostic only: the dispose ladder below is the authoritative teardown
+      // for a runtime that cannot answer shutdown anymore.
+      this.appendStderr([`shutdown request failed: ${errorMessage(error)}`])
+    }
+    await disposeRuntimeProcess(child, {
+      disposeEofGraceMs: this.options.disposeEofGraceMs ?? 6_000,
+      disposeGraceMs: this.options.disposeGraceMs ?? 3_000,
+    })
+    this.transport?.close()
+    this.failSubscriptions(this.closedError('DeepSeek Harness runtime closed'))
+  }
+
+  private dispatchNotification(notification: HarnessNotification): void {
+    this.recordSessionRelationship(notification)
+    for (const subscription of this.subscriptions.values()) subscription.push(notification)
+  }
+
+  private recordSessionRelationship(notification: HarnessNotification): void {
+    if (notification.method !== 'subagent.started') return
+    const parentId = notification.params.parentSessionId
+    const childId = notification.params.childSessionId
+    if (typeof parentId === 'string' && parentId !== '' && typeof childId === 'string' && childId !== '' && parentId !== childId) {
+      this.sessionParents.set(childId, parentId)
+    }
+  }
+
+  private isDescendantOf(sessionId: string, rootSessionId: string): boolean {
+    const visited = new Set<string>()
+    let current = sessionId
+    while (!visited.has(current)) {
+      if (current === rootSessionId) return true
+      visited.add(current)
+      const parent = this.sessionParents.get(current)
+      if (parent === undefined) return false
+      current = parent
+    }
+    // The parent map only ever extends chains upward, so a cycle cannot form.
+    /* v8 ignore next */
+    return false
+  }
+
+  private failSubscriptions(error: Error): void {
+    for (const subscription of this.subscriptions.values()) subscription.fail(error)
+  }
+
+  private appendStderr(lines: string[]): void {
+    const kept = lines.filter(line => line.length > 0)
+    this.stderrTail.push(...kept)
+    if (this.stderrTail.length > STDERR_TAIL_LIMIT) {
+      this.stderrTail.splice(0, this.stderrTail.length - STDERR_TAIL_LIMIT)
+    }
+  }
+
+  private settleStreams(): Promise<void> {
+    return Promise.race([
+      this.streamsSettled,
+      new Promise<void>((resolve) => { setTimeout(resolve, STREAM_SETTLE_MS) }),
+    ])
+  }
+
+  private closedError(reason: string): TransportClosedError {
+    const parts = [reason]
+    if (this.spawnError !== undefined) parts.push(`spawn error: ${this.spawnError.message}`)
+    if (this.exitCode !== undefined) parts.push(`exit code: ${String(this.exitCode)}`)
+    if (this.stderrTail.length > 0) parts.push(`stderr tail:\n${this.stderrTail.join('\n')}`)
+    return new TransportClosedError(parts.join('\n'))
+  }
+}
+
+/**
+ * Whether `value` is a plain JSON object (the wire-boundary shape probe).
+ * @param value - the wire value to probe.
+ * @returns `true` iff `value` is a non-null, non-array object.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** The message of a thrown value (the transport only throws `Error`s; `String` covers the rest). */
+function errorMessage(error: unknown): string {
+  /* v8 ignore next -- the transport and dispose ladder reject only with Errors */
+  return error instanceof Error ? error.message : String(error)
+}

packages/sdk/sdk-client/src/dispose.ts

@@ -0,0 +1,99 @@
+/**
+ * Private teardown ladder for the runtime subprocess: stdin EOF (cooperative
+ * quiesce), then SIGTERM, then SIGKILL, resolving only after the process has
+ * actually exited. The SDK client runs OUTSIDE any harness context, so it
+ * cannot ride the `dsh-subprocess` service — this module is the seam's
+ * documented exception for SDK-managed transports.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/dispose
+ */
+
+import type { ChildProcess } from 'node:child_process'
+
+/**
+ * Race the child's exit against a timer. Neither outcome leaves anything
+ * behind on the child: the exit listener is removed on timeout and the timer
+ * is cleared on exit, so the ladder's tiers never accumulate listeners.
+ */
+function exitsWithin(child: ChildProcess, ms: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true)
+  return new Promise<boolean>((resolve) => {
+    const onExit = (): void => {
+      clearTimeout(timer)
+      resolve(true)
+    }
+    // `.unref()` so a pending grace timer never keeps the parent's loop alive.
+    const timer = setTimeout(() => {
+      child.removeListener('exit', onExit)
+      resolve(false)
+    }, ms).unref()
+    child.once('exit', onExit)
+  })
+}
+
+/** Force-terminate the runtime and reject if no exit edge arrives within the grace. */
+function forceTerminateWithin(child: ChildProcess, ms: number): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise<void>((resolve, reject) => {
+    let accepted = false
+    let settled = false
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      child.off('exit', onExit)
+      child.off('error', onError)
+    }
+    const settle = (complete: () => void): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      complete()
+    }
+    const onExit = (): void => { settle(resolve) }
+    const onError = (error: Error): void => { settle(() => { reject(error) }) }
+    child.once('exit', onExit)
+    child.once('error', onError)
+    const timer = setTimeout(() => {
+      const disposition = accepted ? 'accepted' : 'refused'
+      settle(() => {
+        reject(new Error(`runtime process did not exit within ${ms}ms after SIGKILL was ${disposition}`))
+      })
+    }, ms).unref()
+    try {
+      accepted = child.kill('SIGKILL')
+      if (child.exitCode !== null || child.signalCode !== null) settle(resolve)
+    } catch (error: unknown) {
+      settle(() => { reject(new Error('SIGKILL failed', { cause: error })) })
+    }
+  })
+}
+
+/**
+ * Tear the runtime down to quiescence, resolving only after exit: close stdin
+ * and allow cooperative flush, then use the host's graceful and forced
+ * termination semantics. POSIX sends `SIGTERM` before `SIGKILL`; Windows
+ * skips directly to forced termination because Node maps both signals to
+ * `TerminateProcess`.
+ * @param child - the runtime child process to tear down.
+ * @param graces - the EOF and termination-confirmation windows (ms).
+ * @param platform - the host platform, injectable for unit coverage.
+ * @throws When forced termination errors or the child does not report exit
+ * within `disposeGraceMs`.
+ */
+export async function disposeRuntimeProcess(
+  child: ChildProcess,
+  graces: { disposeEofGraceMs: number; disposeGraceMs: number },
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  // Already gone: nothing to reap.
+  if (child.exitCode !== null || child.signalCode !== null) return
+  // 1. Close stdin and allow cooperative teardown and durable-state flush.
+  child.stdin?.end()
+  if (await exitsWithin(child, graces.disposeEofGraceMs)) return
+  // 2. POSIX gets a catchable graceful signal; Windows signals all force-terminate.
+  if (platform !== 'win32') {
+    child.kill('SIGTERM')
+    if (await exitsWithin(child, graces.disposeGraceMs)) return
+  }
+  // 3. Force-kill and await a bounded exit edge.
+  await forceTerminateWithin(child, graces.disposeGraceMs)
+}

packages/sdk/sdk-client/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * TypeScript client SDK for the DeepSeek Harness runtime: spawn the
+ * `dsh-jsonrpc-agent` runtime as a subprocess and drive agent turns over
+ * stdio JSON-RPC. `DeepSeekHarness` is the high-level turns API;
+ * `HarnessClient` is the lower-level protocol client. A pure library — it
+ * registers nothing on a Cordis context; the runtime process it spawns is a
+ * complete harness configured by its own `cordis.yml`.
+ *
+ * @module @deepseek-ai/dsh-sdk-client
+ */
+
+export * from './api.ts'
+export * from './client.ts'
+export type * from './types.ts'

packages/sdk/sdk-client/src/invariant.ts

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

packages/sdk/sdk-client/src/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Types for the TypeScript SDK client: launch options, notification shapes,
+ * and turn results.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/types
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SdkRunStatus } from '@deepseek-ai/dsh-sdk-protocol'
+
+/** One server-to-client notification as received off the wire. */
+export interface HarnessNotification {
+  /** The JSON-RPC method name (`session.event`, `session.finished`, `subagent.started`, `subagent.finished`). */
+  method: string
+  /** The raw params object; see `HarnessSdkNotificationMap` for the shapes per method. */
+  params: Record<string, unknown>
+}
+
+/** Predicate deciding whether a subscription receives a notification. */
+export type NotificationFilter = (notification: HarnessNotification) => boolean
+
+/** Launch and timeout options for {@link HarnessClient}. */
+export interface HarnessClientOptions {
+  /** The runtime executable (the `dsh-jsonrpc-agent` bin, a packaged exe, or `node`). */
+  command: string
+  /** Arguments passed to {@link command}. */
+  args?: string[]
+  /** Working directory for the runtime process itself. */
+  cwd?: string
+  /**
+   * The complete child environment. `undefined` inherits the parent env
+   * verbatim; passing an object replaces it entirely, so callers own
+   * credential policy (see `scrubbedParentEnv` in `@deepseek-ai/dsh-subprocess`
+   * for the shared scrub-then-merge base).
+   */
+  env?: NodeJS.ProcessEnv
+  /** Per-request timeout (ms); `undefined` waits indefinitely (a turn can legitimately run long). */
+  requestTimeoutMs?: number
+  /** Bound (ms) on the protocol `shutdown` exchange inside `close()` (default 1000). */
+  shutdownTimeoutMs?: number
+  /** Grace (ms) for the runtime's stdin-EOF quiesce during `close()` (default 6000). */
+  disposeEofGraceMs?: number
+  /** Termination confirmation window (ms) after SIGTERM/SIGKILL during `close()` (default 3000). */
+  disposeGraceMs?: number
+}
+
+/** Options for the high-level {@link DeepSeekHarness} wrapper. */
+export interface DeepSeekHarnessOptions {
+  /** Launch spec for the runtime subprocess (command, args, cwd, env, timeouts). */
+  launch: HarnessClientOptions
+  /** Workspace cwd recorded on every SDK-created session (default: the launch cwd, else `process.cwd()`). */
+  cwd?: string
+  /** Provider route for SDK-created agents (default `deepseek`). */
+  provider?: string
+  /** Model for SDK-created agents (default `deepseek-v4-flash`). */
+  model?: string
+}
+
+/** The settled outcome of one {@link HarnessSession.run} turn. */
+export interface TurnResult {
+  /** The session the turn ran on. */
+  sessionId: string
+  /** Deployment-mapped turn outcome from `session.finished`. */
+  status: SdkRunStatus
+  /** Why the last message-triggered turn ended; `undefined` when no turn ran. */
+  reason: TurnEndReason | undefined
+  /** Concatenated text of the session's last assistant message (empty when none). */
+  finalResponse: string
+  /** Every `session.event` payload for this session tree, in wire order. */
+  events: SessionEvent[]
+  /** Every notification observed during the turn, in wire order. */
+  notifications: HarnessNotification[]
+}
+
+/** Re-exported content-block alias so SDK callers need no extra import. */
+export type { ContentBlock }

packages/sdk/sdk-client/tests/dispose.spec.ts

@@ -0,0 +1,231 @@
+/**
+ * Deterministic ladder coverage against a scriptable fake child: each
+ * escalation tier's timing is driven exactly (the client suite exercises the
+ * same ladder against real subprocesses end to end).
+ */
+
+import { EventEmitter } from 'node:events'
+import type { ChildProcess } from 'node:child_process'
+import { describe, expect, it, vi } from 'vitest'
+import { disposeRuntimeProcess } from '../src/dispose.ts'
+
+/** What fells a scripted {@link FakeChild}. */
+type LethalTrigger = 'eof' | NodeJS.Signals
+
+/** Per-scenario script for a {@link FakeChild}. */
+interface FakeChildScript {
+  /**
+   * The one trigger that makes the child exit (SIGKILL always does,
+   * uncatchable, like a real process). Omitted: only SIGKILL fells it.
+   */
+  diesOn?: LethalTrigger
+  /** Delay (ms) between the lethal trigger and the exit event. */
+  delayMs?: number
+  /** Complete the scripted exit inside the triggering call. */
+  synchronousExit?: boolean
+  /** `false` models a child spawned without a stdin pipe. */
+  stdin?: boolean
+}
+
+/**
+ * A scriptable stand-in for a ChildProcess carrying exactly the surface the
+ * ladder reads: `exitCode`/`signalCode`, `stdin.end()`, `kill()`, and the
+ * `exit` event.
+ */
+class FakeChild extends EventEmitter {
+  exitCode: number | null = null
+  signalCode: NodeJS.Signals | null = null
+  readonly kills: NodeJS.Signals[] = []
+  stdinEnded = false
+  readonly stdin: { end: () => void } | null
+
+  constructor(private readonly script: FakeChildScript = {}) {
+    super()
+    this.stdin = script.stdin === false
+      ? null
+      : { end: () => { this.stdinEnded = true; this.maybeDie('eof') } }
+  }
+
+  kill(signal: NodeJS.Signals): boolean {
+    this.kills.push(signal)
+    this.maybeDie(signal)
+    return true
+  }
+
+  private maybeDie(trigger: LethalTrigger): void {
+    // SIGKILL is uncatchable — it always fells the child; any other trigger
+    // only when the scenario scripts it as the lethal one.
+    if (trigger !== 'SIGKILL' && this.script.diesOn !== trigger) return
+    const exit = (): void => {
+      if (trigger === 'eof') this.exitCode = 0
+      else this.signalCode = trigger
+      this.emit('exit', this.exitCode, this.signalCode)
+    }
+    if (this.script.synchronousExit === true) exit()
+    else setTimeout(exit, this.script.delayMs ?? 0)
+  }
+}
+
+/** The ladder takes a real ChildProcess; the fake carries the read surface. */
+function asChild(fake: FakeChild): ChildProcess {
+  return fake as unknown as ChildProcess
+}
+
+describe('disposeRuntimeProcess', () => {
+  it('returns immediately for an already-exited child (no EOF, no signals)', async () => {
+    const fake = new FakeChild()
+    fake.exitCode = 0
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 })
+    expect(fake.stdinEnded).toBe(false)
+    expect(fake.kills).toEqual([])
+  })
+
+  it('returns immediately for a child already dead by signal', async () => {
+    const fake = new FakeChild()
+    fake.signalCode = 'SIGKILL'
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 })
+    expect(fake.stdinEnded).toBe(false)
+    expect(fake.kills).toEqual([])
+  })
+
+  it('tier 1: a cooperative child quiesces on stdin EOF — no signal is ever sent', async () => {
+    const fake = new FakeChild({ diesOn: 'eof', delayMs: 5 })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 })
+    expect(fake.stdinEnded).toBe(true)
+    expect(fake.kills).toEqual([])
+    expect(fake.exitCode).toBe(0)
+  })
+
+  it('recognizes a child that exits synchronously on stdin EOF', async () => {
+    const fake = new FakeChild({ diesOn: 'eof', synchronousExit: true })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 })
+    expect(fake.exitCode).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('tier 2: a child that ignores EOF but honors SIGTERM dies on the middle rung', async () => {
+    const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
+    expect(fake.stdinEnded).toBe(true)
+    expect(fake.kills).toEqual(['SIGTERM'])
+    expect(fake.signalCode).toBe('SIGTERM')
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('recognizes a child that exits synchronously on SIGTERM', async () => {
+    const fake = new FakeChild({ diesOn: 'SIGTERM', synchronousExit: true })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
+    expect(fake.kills).toEqual(['SIGTERM'])
+    expect(fake.signalCode).toBe('SIGTERM')
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('tier 3: a SIGTERM-trapping child is SIGKILLed, and dispose resolves only after the exit', async () => {
+    const fake = new FakeChild({ delayMs: 5 }) // only SIGKILL fells it
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }, 'linux')
+    expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL'])
+    // Quiescence, not a request: at resolution the child has ACTUALLY exited
+    // (the exit event landed, despite the scripted post-SIGKILL delay).
+    expect(fake.signalCode).toBe('SIGKILL')
+  })
+
+  it('recognizes a child already gone when the final exit wait begins', async () => {
+    const fake = new FakeChild({ synchronousExit: true })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }, 'linux')
+    expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL'])
+    expect(fake.signalCode).toBe('SIGKILL')
+  })
+
+  it.each(['exitCode', 'signalCode'] as const)('accepts a late OS %s marker before the final forced wait', async (marker) => {
+    const fake = new FakeChild()
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      queueMicrotask(() => {
+        if (marker === 'exitCode') fake.exitCode = 0
+        else fake.signalCode = 'SIGTERM'
+      })
+      return true
+    })
+
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 1, disposeGraceMs: 10 }, 'linux')
+    expect(fake.kills).toEqual(['SIGTERM'])
+  })
+
+  it('walks the ladder for a child spawned without a stdin pipe', async () => {
+    const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
+    expect(fake.kills).toEqual(['SIGTERM'])
+  })
+
+  it('skips the redundant SIGTERM tier on Windows and awaits forced exit', async () => {
+    const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
+    await disposeRuntimeProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'win32')
+    expect(fake.kills).toEqual(['SIGKILL'])
+    expect(fake.signalCode).toBe('SIGKILL')
+  })
+
+  it('propagates a forced-termination error without waiting for the grace', async () => {
+    const fake = new FakeChild()
+    const failure = Object.assign(new Error('kill EPERM'), { code: 'EPERM' })
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      fake.emit('error', failure)
+      return false
+    })
+
+    await expect(disposeRuntimeProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 1000 },
+      'win32',
+    )).rejects.toBe(failure)
+    expect(fake.kills).toEqual(['SIGKILL'])
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('wraps a synchronous forced-termination exception and removes its listeners', async () => {
+    const fake = new FakeChild()
+    const failure = new Error('invalid signal state')
+    vi.spyOn(fake, 'kill').mockImplementation(() => { throw failure })
+
+    await expect(disposeRuntimeProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 1000 },
+      'win32',
+    )).rejects.toMatchObject({ message: 'SIGKILL failed', cause: failure })
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('bounds a refused forced termination that produces no error or exit', async () => {
+    const fake = new FakeChild()
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      return false
+    })
+
+    await expect(disposeRuntimeProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 10 },
+      'win32',
+    )).rejects.toThrow('runtime process did not exit within 10ms after SIGKILL was refused')
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('bounds an accepted forced termination that never reports exit', async () => {
+    const fake = new FakeChild()
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      return true
+    })
+
+    await expect(disposeRuntimeProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 10 },
+      'win32',
+    )).rejects.toThrow('runtime process did not exit within 10ms after SIGKILL was accepted')
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+})

packages/sdk/sdk-client/tests/fake-runtime.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * Scripted stand-in for the DeepSeek Harness SDK runtime, driven entirely by
+ * env vars — no model, no network, no harness imports. Speaks the runtime's
+ * newline-delimited JSON-RPC protocol on stdio: answers `initialize`,
+ * `session/prompt` (streaming scripted `session.event` notifications, then
+ * `session.finished`, then the response), and `shutdown`.
+ *
+ * Script vocabulary (all optional):
+ * - `FAKE_TEXT`: assistant text for each turn (default `hello from fake runtime`).
+ * - `FAKE_STATUS`: the `session.finished` status (default `ok`).
+ * - `FAKE_REASON_KIND`: the `session.finished` reason kind (default `completed`; `none` omits the reason).
+ * - `FAKE_SUBAGENT`: also emit a child session (subagent.started + child event + subagent.finished).
+ * - `FAKE_ECHO_CWD`: prefix the assistant text with the process cwd.
+ * - `FAKE_ECHO_ENV`: comma-separated env names to echo as `name=value` lines in the assistant text.
+ * - `FAKE_MALFORMED`: `initialize` returns `{}` (no serverInfo); `prompt` returns `{}` (no accepted).
+ * - `FAKE_MALFORMED_PROMPT`: `initialize` is normal; only `prompt` returns `{}` (no accepted).
+ * - `FAKE_INIT_ERROR`: `initialize` answers a JSON-RPC error response with code 7.
+ * - `FAKE_INIT_ERROR_ONCE_FILE`: fail `initialize` (code 7) only when this
+ *   marker file does NOT exist yet, creating it — so the first runtime
+ *   process fails the handshake and a respawned one succeeds (retry probe).
+ * - `FAKE_ECHO_CWD_IN_INIT`: reply `serverInfo.version` = this process's cwd
+ *   (wire-visible spawn-cwd probe).
+ * - `FAKE_MALFORMED_EVENT`: the turn's `session.event` carries a number as
+ *   the event; `FAKE_MALFORMED_MESSAGE`: assistant/message content is not an
+ *   array; `FAKE_MESSAGE_WITHOUT_DATA`: assistant/message with no data
+ *   member; `FAKE_MALFORMED_REASON`: `session.finished` reason is a bare
+ *   string (wire-validation probes).
+ * - `FAKE_HANG_INIT`: never answer `initialize` (mid-handshake cancel probe).
+ * - `FAKE_INIT_READY` + `FAKE_INIT_GO`: touch the READY file when `initialize`
+ *   arrives, then poll for the GO file before answering (deterministic
+ *   cancel-during-handshake window).
+ * - `FAKE_HANG_PROMPT`: never answer `session/prompt` (for timeout/dispose tests).
+ * - `FAKE_STREAM_THEN_MALFORMED`: stream a text chunk for the prompt, then
+ *   answer `{}` (no accepted) — same-pipe ordering makes the chunk arrive
+ *   before the protocol failure (partial-output retention probe).
+ * - `FAKE_IGNORE_EOF` + `FAKE_SIGTERM_FILE`: keep running after stdin EOF; touch the file on SIGTERM (ladder probe).
+ * - `FAKE_TRAP_SIGTERM`: with `FAKE_IGNORE_EOF`, survive SIGTERM too (SIGKILL-rung probe).
+ * - `FAKE_EXIT_BEFORE_INIT`: exit 3 immediately (spawn-then-die probe).
+ * - `FAKE_STDERR`: write this line to stderr at boot (diagnostics-tail probe).
+ * - `FAKE_STDERR_NO_NEWLINE`: write this to stderr WITHOUT a newline (buffer-flush probe).
+ * - `FAKE_RECORD_INIT`: append each `initialize` params JSON to this file (handshake probe).
+ */
+
+import { appendFileSync, existsSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { createInterface } from 'node:readline'
+
+const env = process.env
+
+if (env.FAKE_STDERR !== undefined) process.stderr.write(`${env.FAKE_STDERR}\n`)
+if (env.FAKE_STDERR_NO_NEWLINE !== undefined) process.stderr.write(env.FAKE_STDERR_NO_NEWLINE)
+if (env.FAKE_EXIT_BEFORE_INIT !== undefined) process.exit(3)
+
+if (env.FAKE_IGNORE_EOF !== undefined) {
+  // Simulate a runtime that never quiesces from EOF so the dispose ladder
+  // must escalate; record which rung fired.
+  process.stdin.resume()
+  process.stdin.on('end', () => { setInterval(() => {}, 1_000) })
+  process.on('SIGTERM', () => {
+    if (env.FAKE_SIGTERM_FILE !== undefined) writeFileSync(env.FAKE_SIGTERM_FILE, 'sigterm\n')
+    if (env.FAKE_TRAP_SIGTERM === undefined) process.exit(0)
+  })
+}
+
+function write(message: object): void {
+  process.stdout.write(`${JSON.stringify(message)}\n`)
+}
+
+function notify(method: string, params: object): void {
+  write({ jsonrpc: '2.0', method, params })
+}
+
+let seq = 0
+function event(sessionId: string, type: string, data: object): void {
+  notify('session.event', { sessionId, event: { type, seq: seq++, time: 0, data } })
+}
+
+function assistantText(): string {
+  const parts: string[] = []
+  if (env.FAKE_ECHO_CWD !== undefined) parts.push(`cwd=${process.cwd()}`)
+  for (const name of (env.FAKE_ECHO_ENV ?? '').split(',').filter(entry => entry.length > 0)) {
+    parts.push(`${name}=${env[name] ?? ''}`)
+  }
+  parts.push(env.FAKE_TEXT ?? 'hello from fake runtime')
+  return parts.join('\n')
+}
+
+function runTurn(sessionId: string): void {
+  const text = assistantText()
+  if (env.FAKE_MALFORMED_EVENT !== undefined) {
+    notify('session.event', { sessionId, event: 42 })
+    return
+  }
+  event(sessionId, 'turn/start', { turn: 0 })
+  event(sessionId, 'assistant/chunk', { turn: 0, step: 0, chunk: { type: 'text-delta', index: 0, text } })
+  if (env.FAKE_MALFORMED_MESSAGE !== undefined) {
+    event(sessionId, 'assistant/message', { turn: 0, step: 0, content: 'not-an-array' })
+    return
+  }
+  if (env.FAKE_MESSAGE_WITHOUT_DATA !== undefined) {
+    notify('session.event', { sessionId, event: { type: 'assistant/message', seq: seq++, time: 0 } })
+    return
+  }
+  event(sessionId, 'assistant/message', {
+    turn: 0,
+    step: 0,
+    content: [{ type: 'text', text }],
+    provenance: { provider: 'fake', model: 'fake' },
+  })
+  const reasonKind = env.FAKE_REASON_KIND ?? 'completed'
+  event(sessionId, 'turn/end', { turn: 0, reason: { kind: reasonKind } })
+  if (env.FAKE_SUBAGENT !== undefined) {
+    const childId = `${sessionId}-child`
+    notify('subagent.started', { parentSessionId: sessionId, childSessionId: childId })
+    event(childId, 'assistant/message', {
+      turn: 0,
+      step: 0,
+      content: [{ type: 'text', text: 'child says hi' }],
+      provenance: { provider: 'fake', model: 'fake' },
+    })
+    notify('subagent.finished', {
+      provider: 'spawn',
+      agentId: childId,
+      parentSessionId: sessionId,
+      childSessionId: childId,
+      status: 'ok',
+      stopReason: 'completed',
+      lastAssistantMessage: [{ type: 'text', text: 'child says hi' }],
+    })
+  }
+  notify('session.finished', {
+    sessionId,
+    status: env.FAKE_STATUS ?? 'ok',
+    ...(env.FAKE_MALFORMED_REASON !== undefined
+      ? { reason: 'not-a-record' }
+      : reasonKind === 'none' ? {} : { reason: { kind: reasonKind } }),
+  })
+}
+
+function sessionIdOf(params: Record<string, unknown> | undefined): string {
+  const value = params?.sessionId
+  return typeof value === 'string' ? value : ''
+}
+
+const reader = createInterface({ input: process.stdin })
+reader.on('line', (line) => {
+  if (line.trim().length === 0) return
+  const frame = JSON.parse(line) as { id?: string | number; method?: string; params?: Record<string, unknown> }
+  if (frame.method === undefined || frame.id === undefined) return
+  const respond = (result: object): void => { write({ jsonrpc: '2.0', id: frame.id, result }) }
+  switch (frame.method) {
+    case 'initialize':
+      if (env.FAKE_RECORD_INIT !== undefined) appendFileSync(env.FAKE_RECORD_INIT, `${JSON.stringify(frame.params)}\n`)
+      if (env.FAKE_HANG_INIT !== undefined) return
+      if (env.FAKE_INIT_READY !== undefined && env.FAKE_INIT_GO !== undefined) {
+        writeFileSync(env.FAKE_INIT_READY, 'ready\n')
+        const go = env.FAKE_INIT_GO
+        const id = frame.id
+        const poll = setInterval(() => {
+          if (!existsSync(go)) return
+          clearInterval(poll)
+          write({ jsonrpc: '2.0', id, result: { serverInfo: { name: 'deepseek-harness-sdk-runtime', version: '0.0.1' } } })
+        }, 5)
+        return
+      }
+      if (env.FAKE_INIT_ERROR !== undefined) {
+        write({ jsonrpc: '2.0', id: frame.id, error: { code: 7, message: 'scripted init failure', data: { hint: 'fake' } } })
+        return
+      }
+      if (env.FAKE_INIT_ERROR_ONCE_FILE !== undefined && !existsSync(env.FAKE_INIT_ERROR_ONCE_FILE)) {
+        writeFileSync(env.FAKE_INIT_ERROR_ONCE_FILE, 'failed-once\n')
+        write({ jsonrpc: '2.0', id: frame.id, error: { code: 7, message: 'scripted first-boot failure' } })
+        return
+      }
+      if (env.FAKE_MALFORMED !== undefined) {
+        respond({})
+        return
+      }
+      if (env.FAKE_ECHO_CWD_IN_INIT !== undefined) {
+        respond({ serverInfo: { name: 'deepseek-harness-sdk-runtime', version: process.cwd() } })
+        return
+      }
+      respond({ serverInfo: { name: 'deepseek-harness-sdk-runtime', version: '0.0.1' } })
+      return
+    case 'session/prompt': {
+      if (env.FAKE_STREAM_THEN_MALFORMED !== undefined) {
+        const sessionId = sessionIdOf(frame.params)
+        event(sessionId, 'assistant/chunk', { turn: 0, step: 0, chunk: { type: 'text-delta', index: 0, text: 'streamed then cut short' } })
+        respond({})
+        return
+      }
+      if (env.FAKE_HANG_PROMPT !== undefined) return
+      if (env.FAKE_MALFORMED !== undefined || env.FAKE_MALFORMED_PROMPT !== undefined) {
+        respond({})
+        return
+      }
+      const sessionId = sessionIdOf(frame.params)
+      runTurn(sessionId)
+      respond({ accepted: true })
+      return
+    }
+    case 'shutdown':
+      respond({})
+      // An EOF-ignoring fake also refuses the protocol exit, so the client's
+      // dispose ladder (not this cooperative path) must reap it.
+      if (env.FAKE_IGNORE_EOF === undefined) setImmediate(() => process.exit(0))
+      return
+    default:
+      write({ jsonrpc: '2.0', id: frame.id, error: { code: -32603, message: `unknown method: ${frame.method}` } })
+  }
+})

packages/sdk/sdk-client/tests/sdk-client.spec.ts

@@ -0,0 +1,478 @@
+/**
+ * SDK client against a real scripted runtime subprocess
+ * (`tests/fake-runtime.ts`, protocol-only — the only faked boundary is the
+ * model-owning runtime itself). Covers the turn loop, notification routing
+ * and session-tree scoping, error surfaces, timeouts, and the dispose ladder.
+ */
+
+import { mkdir, mkdtemp, readFile, realpath, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { isAbsolute, join, relative, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  DeepSeekHarness,
+  finalResponse,
+  HarnessClient,
+  normalizeInput,
+  RequestTimeoutError,
+  SdkProtocolError,
+  TransportClosedError,
+  type HarnessNotification,
+} from '../src/index.ts'
+import { JsonRpcResponseError } from '@deepseek-ai/dsh-sdk-protocol'
+
+const fakeRuntime = fileURLToPath(new URL('./fake-runtime.ts', import.meta.url))
+
+const cleanups: (() => Promise<void>)[] = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup()
+})
+
+type LaunchOverrides = Partial<ConstructorParameters<typeof HarnessClient>[0]>
+
+/** Launch options running the fake runtime on the current node (type stripping). */
+function fakeLaunch(env: Record<string, string> = {}, extra: LaunchOverrides = {}) {
+  return {
+    command: process.execPath,
+    args: [fakeRuntime],
+    env: { ...process.env as Record<string, string>, ...env },
+    ...extra,
+  }
+}
+
+function harnessWith(env: Record<string, string> = {}, extra: LaunchOverrides = {}): DeepSeekHarness {
+  const harness = new DeepSeekHarness({ launch: fakeLaunch(env, extra) })
+  cleanups.push(() => harness.close())
+  return harness
+}
+
+async function tempDir(prefix: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), prefix))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+describe('DeepSeekHarness', () => {
+  it('runs a turn end to end and reuses the runtime across sessions', async () => {
+    const harness = harnessWith({ FAKE_TEXT: 'turn answer' })
+    const first = await harness.run('say hi')
+    expect(first.status).toBe('ok')
+    expect(first.reason).toEqual({ kind: 'completed' })
+    expect(first.finalResponse).toBe('turn answer')
+    expect(first.events.map(event => event.type)).toEqual(['turn/start', 'assistant/chunk', 'assistant/message', 'turn/end'])
+
+    // Same subprocess, second session: ids differ, protocol state is reusable.
+    const second = await harness.run([{ type: 'text', text: 'again' }])
+    expect(second.status).toBe('ok')
+    expect(second.sessionId).not.toBe(first.sessionId)
+    await harness.close()
+  })
+
+  it('streams notifications to the observer and scopes them to the session tree', async () => {
+    const harness = harnessWith({ FAKE_SUBAGENT: '1' })
+    const seen: HarnessNotification[] = []
+    const result = await harness.run('delegate', {
+      sessionId: 'parent-1',
+      onNotification: (n) => { seen.push(n) },
+    })
+
+    expect(result.status).toBe('ok')
+    // The child session's events arrive through subagent.started lineage.
+    expect(seen.map(n => n.method)).toContain('subagent.started')
+    expect(seen.map(n => n.method)).toContain('subagent.finished')
+    const childEvents = seen.filter(n => n.method === 'session.event' && n.params.sessionId === 'parent-1-child')
+    expect(childEvents.length).toBeGreaterThan(0)
+    // Child events do not count as the parent's own turn events.
+    expect(result.events.every(event => event.type !== 'assistant/message'
+      || (event.data as { content: { type: string; text?: string }[] }).content[0]?.text !== 'child says hi')).toBe(true)
+    await harness.close()
+  })
+
+  it('reports an error status with the turn-end reason', async () => {
+    const harness = harnessWith({ FAKE_STATUS: 'error', FAKE_REASON_KIND: 'max-tokens' })
+    const result = await harness.run('overflow')
+    expect(result.status).toBe('error')
+    expect(result.reason).toEqual({ kind: 'max-tokens' })
+    await harness.close()
+  })
+
+  it('omits the reason when the runtime settled without one', async () => {
+    const harness = harnessWith({ FAKE_STATUS: 'error', FAKE_REASON_KIND: 'none' })
+    const result = await harness.run('no turn')
+    expect(result.status).toBe('error')
+    expect(result.reason).toBeUndefined()
+    await harness.close()
+  })
+
+  it('sends the configured cwd/provider/model in the handshake exactly once', async () => {
+    const dir = await tempDir('sdk-client-init-')
+    const recordFile = join(dir, 'init.jsonl')
+    const harness = new DeepSeekHarness({
+      launch: fakeLaunch({ FAKE_RECORD_INIT: recordFile }),
+      cwd: dir,
+      provider: 'custom-provider',
+      model: 'custom-model',
+    })
+    cleanups.push(() => harness.close())
+    await harness.run('one')
+    await harness.run('two')
+    await harness.close()
+    const records = (await readFile(recordFile, 'utf8')).trim().split('\n').map(line => JSON.parse(line) as object)
+    expect(records).toEqual([{ cwd: dir, provider: 'custom-provider', model: 'custom-model' }])
+  })
+
+  it('resolves a relative launch cwd to an absolute workspace before the handshake', async () => {
+    // vitest workers forbid chdir, so derive a RELATIVE path from the real
+    // process cwd to a temp worker dir; resolution is lexical either way.
+    const dir = await tempDir('sdk-client-relcwd-')
+    const recordFile = join(dir, 'init.jsonl')
+    const inner = join(dir, 'worker')
+    await mkdir(inner)
+    const relativeCwd = relative(process.cwd(), inner)
+    expect(isAbsolute(relativeCwd)).toBe(false)
+    const harness = new DeepSeekHarness({
+      launch: fakeLaunch({ FAKE_RECORD_INIT: recordFile, FAKE_ECHO_CWD_IN_INIT: '1' }, { cwd: relativeCwd }),
+    })
+    cleanups.push(() => harness.close())
+    await harness.start()
+    const identity = await harness.client.initialize({ cwd: inner, provider: 'p', model: 'm' })
+    await harness.close()
+    // The child spawned under the temp worker dir (its physical cwd)...
+    expect(identity.serverInfo.version).toBe(await realpath(inner))
+    // ...and the handshake wire cwd went out ABSOLUTE, so the child cannot
+    // re-resolve a relative string into dir/worker/worker.
+    const records = (await readFile(recordFile, 'utf8')).trim().split('\n')
+      .map(line => (JSON.parse(line) as { cwd: string }).cwd)
+    expect(records).toEqual([resolvePath(relativeCwd), inner])
+  })
+
+  it('propagates a JSON-RPC error response from initialize and closes the runtime', async () => {
+    const harness = harnessWith({ FAKE_INIT_ERROR: '1' })
+    const failure = await harness.run('boom').then(
+      () => { throw new Error('run unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(failure).toBeInstanceOf(JsonRpcResponseError)
+    expect(failure).toMatchObject({ code: 7, message: 'scripted init failure', data: { hint: 'fake' } })
+    // The failed handshake reset lets a later start retry instead of wedging.
+    await expect(harness.run('later')).rejects.toThrow()
+  })
+
+  it('retries a failed handshake with a fresh runtime process', async () => {
+    const dir = await tempDir('sdk-client-retry-')
+    const marker = join(dir, 'first-boot-failed')
+    const harness = harnessWith({ FAKE_INIT_ERROR_ONCE_FILE: marker, FAKE_TEXT: 'second boot answer' })
+    const firstClient = harness.client
+    // First start: the scripted runtime fails the handshake and is reaped.
+    await expect(harness.start()).rejects.toThrow('scripted first-boot failure')
+    // Retry spawns a NEW subprocess through a fresh client (close is permanent).
+    const result = await harness.run('again')
+    expect(harness.client).not.toBe(firstClient)
+    expect(result.status).toBe('ok')
+    expect(result.finalResponse).toBe('second boot answer')
+    await harness.close()
+    // close() is terminal: a handshake failure after it must not respawn.
+    await expect(harness.run('after-close')).rejects.toThrow(TransportClosedError)
+  })
+
+  it('rejects a malformed initialize result as a protocol error', async () => {
+    const harness = harnessWith({ FAKE_MALFORMED: '1' })
+    await expect(harness.run('bad')).rejects.toThrow(SdkProtocolError)
+  })
+
+  it('supports await using disposal', async () => {
+    let captured: DeepSeekHarness
+    {
+      await using harness = new DeepSeekHarness({ launch: fakeLaunch() })
+      captured = harness
+      const result = await harness.run('scoped')
+      expect(result.status).toBe('ok')
+    }
+    // After scope exit the runtime is closed: reuse fails loudly.
+    await expect(captured.run('after')).rejects.toThrow(TransportClosedError)
+  })
+})
+
+describe('HarnessClient', () => {
+  it('times out a hung request at the per-call bound', async () => {
+    const client = new HarnessClient(fakeLaunch({ FAKE_HANG_PROMPT: '1' }))
+    cleanups.push(() => client.close())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    await expect(client.request('session/prompt', { sessionId: 's', contentBlocks: normalizeInput('hi') }, 200))
+      .rejects.toThrow(RequestTimeoutError)
+    await client.close()
+  })
+
+  it('a timed-out request leaves no pending transport state', async () => {
+    const client = new HarnessClient(fakeLaunch({ FAKE_HANG_PROMPT: '1' }))
+    cleanups.push(() => client.close())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    for (let round = 0; round < 3; round++) {
+      await expect(client.request('session/prompt', { sessionId: 's', contentBlocks: normalizeInput('x') }, 50))
+        .rejects.toThrow(RequestTimeoutError)
+    }
+    // Abandonment removed each pending entry at its timeout; a hung method
+    // retains nothing per call. (Private map read is the observable here —
+    // no wire surface reports transport bookkeeping.)
+    const transport = (client as unknown as { transport: { pending: Map<string, unknown> } }).transport
+    expect(transport.pending.size).toBe(0)
+    await client.close()
+  })
+
+  it('applies the client-wide request timeout when no per-call bound is given', async () => {
+    const client = new HarnessClient(fakeLaunch({ FAKE_HANG_PROMPT: '1' }, { requestTimeoutMs: 400 }))
+    cleanups.push(() => client.close())
+    // The bound applies from send, so it holds regardless of runtime boot time.
+    await expect(client.prompt('s', normalizeInput('hi'))).rejects.toThrow(RequestTimeoutError)
+    await client.close()
+  })
+
+  it('rejects a malformed prompt acceptance as a protocol error', async () => {
+    const client = new HarnessClient(fakeLaunch({ FAKE_MALFORMED: '1' }))
+    cleanups.push(() => client.close())
+    await expect(client.prompt('s', normalizeInput('hi'))).rejects.toThrow(SdkProtocolError)
+    await client.close()
+  })
+
+  it('fails pending requests with exit code and stderr tail when the runtime dies', async () => {
+    const client = new HarnessClient(fakeLaunch({ FAKE_EXIT_BEFORE_INIT: '1', FAKE_STDERR: 'fatal: scripted death' }))
+    cleanups.push(() => client.close())
+    const failure = await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' }).then(
+      () => { throw new Error('initialize unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(failure).toBeInstanceOf(TransportClosedError)
+    expect(String(failure)).toContain('exit code: 3')
+    expect(String(failure)).toContain('fatal: scripted death')
+    // Requests after death fail immediately with the same context.
+    await expect(client.request('initialize', {})).rejects.toThrow('exit code: 3')
+  })
+
+  it('flushes an unterminated stderr line into the tail at close', async () => {
+    const client = new HarnessClient(fakeLaunch({ FAKE_STDERR_NO_NEWLINE: 'no trailing newline', FAKE_EXIT_BEFORE_INIT: '1' }))
+    cleanups.push(() => client.close())
+    const failure = await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' }).then(
+      () => { throw new Error('initialize unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(String(failure)).toContain('no trailing newline')
+  })
+
+  it('fails fast when the command does not exist', async () => {
+    const client = new HarnessClient({ command: join(tmpdir(), 'dsh-no-such-runtime-bin') })
+    cleanups.push(() => client.close())
+    await expect(client.request('initialize', {}, 1_000)).rejects.toThrow(TransportClosedError)
+  })
+
+  it('close() is idempotent, reaps the child, and fails later use', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    await Promise.all([client.close(), client.close()])
+    expect(() => { client.start() }).toThrow(TransportClosedError)
+    await expect(client.request('anything')).rejects.toThrow(TransportClosedError)
+    // Close with no child ever spawned is a no-op.
+    const untouched = new HarnessClient(fakeLaunch())
+    await untouched.close()
+  })
+
+  it('escalates through SIGTERM when the runtime ignores EOF', async () => {
+    const dir = await tempDir('sdk-client-ladder-')
+    const sigtermFile = join(dir, 'sigterm.txt')
+    const client = new HarnessClient(fakeLaunch(
+      { FAKE_IGNORE_EOF: '1', FAKE_SIGTERM_FILE: sigtermFile },
+      { shutdownTimeoutMs: 100, disposeEofGraceMs: 100, disposeGraceMs: 1_000 },
+    ))
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    await client.close()
+    expect((await stat(sigtermFile)).isFile()).toBe(true)
+  })
+
+  it('escalates to SIGKILL when the runtime traps SIGTERM too', async () => {
+    const client = new HarnessClient(fakeLaunch(
+      { FAKE_IGNORE_EOF: '1', FAKE_TRAP_SIGTERM: '1' },
+      { shutdownTimeoutMs: 100, disposeEofGraceMs: 100, disposeGraceMs: 300 },
+    ))
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    // Resolves (does not hang or reject): the SIGKILL rung reaped the child.
+    await client.close()
+  })
+
+  it('delivers notifications to unfiltered and filtered subscriptions in wire order', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    cleanups.push(() => client.close())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+
+    const all = client.subscribe()
+    const finishedOnly = client.subscribe(n => n.method === 'session.finished')
+    await client.prompt('sub-test', normalizeInput('go'))
+
+    const first = await all.next()
+    expect(first.method).toBe('session.event')
+    const finished = await finishedOnly.next()
+    expect(finished.method).toBe('session.finished')
+    expect(finishedOnly.tryNext()).toBeUndefined()
+
+    // A bare unbounded request with omitted params sends `{}` on the wire.
+    const identity = await client.request('initialize') as { serverInfo: { name: string } }
+    expect(identity.serverInfo.name).toBe('deepseek-harness-sdk-runtime')
+
+    // Async iteration consumes queued items and then parks.
+    const collected: string[] = []
+    for await (const notification of all) {
+      collected.push(notification.method)
+      if (notification.method === 'session.finished') break
+    }
+    expect(collected.at(-1)).toBe('session.finished')
+
+    all.close()
+    finishedOnly.close()
+    await expect(all.next()).rejects.toThrow('notification subscription closed')
+    await client.close()
+  })
+
+  it('contains a throwing filter to its own subscription', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    cleanups.push(() => client.close())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+
+    const broken = client.subscribe(() => { throw new Error('filter exploded') })
+    // A non-Error throw is normalized rather than crashing dispatch.
+    const brokenNonError = client.subscribe(() => { throw 'string boom' })
+    const healthy = client.subscribe(n => n.method === 'session.finished')
+    await client.prompt('filter-contain', normalizeInput('go'))
+
+    // The sibling subscription and the read loop are undisturbed.
+    expect((await healthy.next()).method).toBe('session.finished')
+    // Each broken subscription failed with ITS OWN error and detached.
+    await expect(broken.next()).rejects.toThrow('filter exploded')
+    await expect(brokenNonError.next()).rejects.toThrow('string boom')
+    healthy.close()
+    await client.close()
+  })
+
+  it('close() drops queued notifications; runtime death keeps them drainable', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    const closed = client.subscribe()
+    const drainable = client.subscribe()
+    await client.prompt('queue-drop', normalizeInput('go'))
+    expect(closed.tryNext()).toBeDefined()
+    closed.close()
+    // Manual close drops the rest of the queue outright.
+    expect(closed.tryNext()).toBeUndefined()
+    await expect(closed.next()).rejects.toThrow('notification subscription closed')
+    // Runtime teardown, by contrast, only stops FUTURE delivery: what was
+    // already delivered before close() stays drainable.
+    await client.close()
+    expect(drainable.tryNext()).toBeDefined()
+  })
+
+  it('subscriptions created after termination are born failed', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    await client.close()
+    // No producer can ever feed this subscription; next() must not park forever.
+    await expect(client.subscribe().next()).rejects.toThrow(TransportClosedError)
+
+    const dead = new HarnessClient(fakeLaunch({ FAKE_EXIT_BEFORE_INIT: '1' }))
+    cleanups.push(() => dead.close())
+    await dead.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' }).catch(() => {})
+    await expect(dead.subscribe().next()).rejects.toThrow(TransportClosedError)
+  })
+
+  it('closes subscriptions with the runtime and rejects parked waiters', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+    const subscription = client.subscribe()
+    const parked = subscription.next()
+    await client.close()
+    await expect(parked).rejects.toThrow(TransportClosedError)
+  })
+
+  it('scopes the session tree across multi-hop lineage and ignores foreign sessions', async () => {
+    const client = new HarnessClient(fakeLaunch())
+    cleanups.push(() => client.close())
+    await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' })
+
+    const tree = client.subscribeSessionTree('root')
+    // Lineage edges arrive as subagent.started notifications.
+    const inject = (method: string, params: Record<string, unknown>): void => {
+      (client as unknown as { dispatchNotification(n: HarnessNotification): void }).dispatchNotification({ method, params })
+    }
+    inject('subagent.started', { parentSessionId: 'root', childSessionId: 'child' })
+    inject('subagent.started', { parentSessionId: 'child', childSessionId: 'grandchild' })
+    inject('session.event', { sessionId: 'grandchild', event: { type: 'noop' } })
+    inject('session.event', { sessionId: 'stranger', event: { type: 'noop' } })
+    inject('subagent.started', { parentSessionId: 'other-root', childSessionId: 'other-child' })
+    inject('subagent.finished', { parentSessionId: 'child', childSessionId: 'grandchild' })
+    // Self-loop and empty edges must not corrupt the lineage map.
+    inject('subagent.started', { parentSessionId: 'loop', childSessionId: 'loop' })
+    inject('subagent.started', { parentSessionId: '', childSessionId: 'x' })
+    inject('subagent.finished', { childSessionId: 'root' })
+
+    expect((await tree.next()).method).toBe('subagent.started')
+    expect((await tree.next()).method).toBe('subagent.started')
+    expect((await tree.next()).params.sessionId).toBe('grandchild')
+    expect((await tree.next()).method).toBe('subagent.finished')
+    // The foreign-root edge and stranger event were filtered; next is the root-child edge.
+    expect((await tree.next()).params.childSessionId).toBe('root')
+    tree.close()
+    await client.close()
+  })
+})
+
+describe('wire payload validation', () => {
+  it('rejects a non-object session.event envelope as a protocol error', async () => {
+    const harness = harnessWith({ FAKE_MALFORMED_EVENT: '1' })
+    await expect(harness.run('bad-event')).rejects.toThrow(SdkProtocolError)
+  })
+
+  it('rejects an assistant/message without a content array as a protocol error', async () => {
+    const harness = harnessWith({ FAKE_MALFORMED_MESSAGE: '1' })
+    await expect(harness.run('bad-message')).rejects.toThrow(SdkProtocolError)
+  })
+
+  it('rejects an assistant/message without a data member as a protocol error', async () => {
+    const harness = harnessWith({ FAKE_MESSAGE_WITHOUT_DATA: '1' })
+    await expect(harness.run('no-data')).rejects.toThrow(SdkProtocolError)
+  })
+
+  it('rejects a malformed session.finished reason as a protocol error', async () => {
+    const harness = harnessWith({ FAKE_MALFORMED_REASON: '1' })
+    await expect(harness.run('bad-reason')).rejects.toThrow(SdkProtocolError)
+  })
+})
+
+describe('stderr tail bound', () => {
+  it('keeps only the newest lines up to the limit', async () => {
+    const manyLines = Array.from({ length: 450 }, (_, i) => `line-${i}`).join('\n')
+    const client = new HarnessClient(fakeLaunch({ FAKE_STDERR: manyLines, FAKE_EXIT_BEFORE_INIT: '1' }))
+    cleanups.push(() => client.close())
+    const failure = await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' }).then(
+      () => { throw new Error('initialize unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    const text = String(failure)
+    // The tail is bounded to the newest 400 lines: the oldest are dropped.
+    expect(text).toContain('line-449')
+    expect(text).not.toContain('line-0\n')
+  })
+})
+
+describe('pure helpers', () => {
+  it('normalizeInput wraps strings and passes blocks through', () => {
+    expect(normalizeInput('x')).toEqual([{ type: 'text', text: 'x' }])
+    const blocks = [{ type: 'text' as const, text: 'y' }]
+    expect(normalizeInput(blocks)).toBe(blocks)
+  })
+
+  it('finalResponse reads the last assistant message and tolerates absence', () => {
+    expect(finalResponse([])).toBe('')
+    expect(finalResponse([{ type: 'turn/start', seq: 0, time: 0, data: { turn: 0 } } as never])).toBe('')
+    expect(finalResponse([
+      { type: 'assistant/message', seq: 0, time: 0, data: { content: [{ type: 'text', text: 'first' }] } } as never,
+      { type: 'assistant/message', seq: 1, time: 0, data: { content: [{ type: 'text', text: 'a' }, { type: 'tool-call' }, { type: 'text', text: 'b' }] } } as never,
+    ])).toBe('ab')
+  })
+})

packages/sdk/sdk-client/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../sdk-protocol"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/sdk/sdk-protocol/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
+README.md: 61ffc0e17700d79da14001b389c7c6dcb50ee28d
+README.zh.md: 9de816dc588354d04194d5eb99f444409456046e

packages/sdk/sdk-protocol/README.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-sdk-protocol
+
+English | [中文](README.zh.md)
+
+The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The server side is the [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) plugin; clients are [`dsh-sdk-client`](../sdk-client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
+
+## Transport
+
+`JsonRpcLineTransport` frames JSON-RPC 2.0 over caller-owned byte streams, one compact JSON frame per `\n`-terminated line. Frames with `id` and `method` are requests, `id` alone is a response, `method` alone is a notification; malformed JSON lines are ignored. `start()` attaches stream listeners, `close()` detaches them and rejects pending requests without destroying the streams. Missing request handlers answer `-32601`; handler rejections answer `-32603` with the error message. An error response rejects the pending `request()` with `JsonRpcResponseError`, which preserves the wire `code` and optional `data`. `JsonRpcTransportPeer` is the outbound surface (request/notify) the server class is typed against.
+
+## Wire types
+
+`types.ts` names every payload of the protocol served by `HarnessSdkServer`:
+
+| Direction | Method | Types |
+|---|---|---|
+| client→server | `initialize` | `InitializeParams` → `InitializeResult` |
+| client→server | `session/prompt` | `SessionPromptParams` → `SessionPromptResult` (answered only after turn settlement) |
+| client→server | `shutdown` | no params → `{}` |
+| server→client | `session.event` | `SessionEventNotification` (every session in the runtime, unfiltered) |
+| server→client | `session.finished` | `SessionFinishedNotification` (one per accepted prompt) |
+| server→client | `subagent.started` | `SubagentStartedNotification` |
+| server→client | `subagent.finished` | `SubagentFinishedNotification` (in-process runs only) |
+
+`HarnessSdkRequestMap` and `HarnessSdkNotificationMap` index these by method name. The notification payload types depend on `SessionEvent` (`dsh-session`), `ContentBlock` (`dsh-llm`), and `SubagentStopReason` (`dsh-subagent`) — the protocol streams full session-log envelopes, so the session vocabulary is part of the wire contract. `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`.
+
+## Model Experience
+
+None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) entry.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No protocol-version negotiation** — the handshake carries only `serverInfo.version` (`0.0.1`, unvalidated by clients); pre-release stance, no compatibility promise.
+- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../ui/jsonrpc/README.md).
+- **Server→client requests are dead capability** — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.

packages/sdk/sdk-protocol/README.zh.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-sdk-protocol
+
+[English](README.md) | 中文
+
+DeepSeek Harness SDK 运行时的共享线协议：一个按换行分帧的 JSON-RPC 2.0 传输类，加上线两端共同使用的具名请求、结果与通知类型。服务端是 [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) 插件；客户端是 [`dsh-sdk-client`](../sdk-client/README.md)（TypeScript）与 [Python SDK](../../../python/README.md)（后者镜像这些形状但不导入它们）。纯库——无插件、无 Config、无注册。
+
+## 传输
+
+`JsonRpcLineTransport` 在调用方持有的字节流上为 JSON-RPC 2.0 分帧，每行一个紧凑 JSON 帧、以 `\n` 结尾。带 `id` 与 `method` 的帧是请求，仅 `id` 是响应，仅 `method` 是通知；非法 JSON 行被忽略。`start()` 挂接流监听器，`close()` 摘除监听器并拒绝挂起请求、但不销毁流。缺失请求处理器时应答 `-32601`；处理器拒绝则应答携带错误消息的 `-32603`。错误响应会以 `JsonRpcResponseError` 拒绝挂起的 `request()`，保留线上的 `code` 与可选 `data`。`JsonRpcTransportPeer` 是服务器类所依赖的出站表面（request/notify）。
+
+## 线类型
+
+`types.ts` 为 `HarnessSdkServer` 所服务协议的每个载荷命名：
+
+| 方向 | 方法 | 类型 |
+|---|---|---|
+| client→server | `initialize` | `InitializeParams` → `InitializeResult` |
+| client→server | `session/prompt` | `SessionPromptParams` → `SessionPromptResult`（仅在回合尘埃落定后应答） |
+| client→server | `shutdown` | 无参数 → `{}` |
+| server→client | `session.event` | `SessionEventNotification`（运行时内每个会话，不过滤） |
+| server→client | `session.finished` | `SessionFinishedNotification`（每个被接受的 prompt 一条） |
+| server→client | `subagent.started` | `SubagentStartedNotification` |
+| server→client | `subagent.finished` | `SubagentFinishedNotification`（仅进程内 run） |
+
+`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇表是线契约的一部分。`serverInfo.name` 保持线上稳定值 `deepseek-harness-sdk-runtime`。
+
+## Model Experience
+
+None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) entry.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **无协议版本协商** —— 握手只携带 `serverInfo.version`（`0.0.1`，客户端不校验）；预发布立场，无兼容承诺。
+- **无取消与会话关闭方法** —— 客户端放弃回合的方式是关闭运行时进程；见 [`dsh-jsonrpc` README](../../ui/jsonrpc/README.md)。
+- **server→client 请求是死能力** —— 传输层支持，但服务器从不发送；Python SDK 的应答表面为未来审批流预留。

packages/sdk/sdk-protocol/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@deepseek-ai/dsh-sdk-protocol",
+  "description": "Shared wire protocol for the DeepSeek Harness SDK runtime: the newline-delimited JSON-RPC stdio transport and the named request, result, and notification types spoken between the runtime server and SDK clients",
+  "version": "0.0.1",
+  "private": true,
+  "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",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/sdk/sdk-protocol/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared wire protocol for the DeepSeek Harness SDK runtime: the
+ * newline-delimited JSON-RPC stdio transport plus the named request, result,
+ * and notification types both wire ends speak. The runtime server plugin
+ * (`@deepseek-ai/dsh-jsonrpc`) serves this protocol; SDK clients
+ * (`@deepseek-ai/dsh-sdk-client`, the Python SDK) drive it.
+ *
+ * @module @deepseek-ai/dsh-sdk-protocol
+ */
+
+export * from './transport.ts'
+export * from './types.ts'

packages/sdk/sdk-protocol/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sdk-protocol`.
+ * @module @deepseek-ai/dsh-sdk-protocol/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-sdk-protocol'
+
+/** Cordis companion plugin name. */
+export const name = 'sdk-protocol-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a pure wire library (transport class + type
+ * declarations) with no event stream or mutable data relation of its own;
+ * both wire ends own their protocol behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/sdk/sdk-protocol/src/transport.ts

@@ -3,7 +3,7 @@
  * `method` are requests, `id` alone is a response, and `method` alone is a
  * notification. Malformed lines are ignored; handler failures become error frames.
  *
- * @module @deepseek-ai/dsh-jsonrpc/transport
+ * @module @deepseek-ai/dsh-sdk-protocol/transport
  */
 
 import { randomUUID } from 'node:crypto'
@@ -14,23 +14,38 @@ type JsonRpcId = string | number
 type RequestHandler = (method: string, params: Record<string, unknown>) => Promise<unknown>
 type NotificationHandler = (method: string, params: Record<string, unknown>) => void
 
+/** A JSON-RPC error response, preserving the wire `code` and optional `data`. */
+export class JsonRpcResponseError extends Error {
+  /**
+   * @param code - the wire error code, or `undefined` when the peer sent none.
+   * @param message - the wire error message.
+   * @param data - the optional structured error payload, verbatim.
+   */
+  constructor(readonly code: number | undefined, message: string, readonly data?: unknown) {
+    super(message)
+    this.name = 'JsonRpcResponseError'
+  }
+}
+
 /**
- * Outbound request and notification surface used by {@link HarnessSdkServer}.
+ * Outbound request and notification surface used by the runtime server and
+ * SDK clients.
  */
 export interface JsonRpcTransportPeer {
   /**
    * Send a request and await its response.
    * @param method - the JSON-RPC method name.
    * @param params - the request parameters object.
-   * @returns the result; rejects on an error response, write failure, or closure.
+   * @returns the result; rejects with {@link JsonRpcResponseError} on an error
+   * response, and with a plain `Error` on a write failure or closure.
    */
-  request(method: string, params: Record<string, unknown>): Promise<unknown>
+  request(method: string, params: object): Promise<unknown>
   /**
    * Send a notification; omitted params produce no `params` member.
    * @param method - the JSON-RPC method name.
    * @param params - the optional notification parameters object.
    */
-  notify(method: string, params?: Record<string, unknown>): void
+  notify(method: string, params?: object): void
 }
 
 interface PendingRequest {
@@ -94,21 +109,53 @@ export class JsonRpcLineTransport implements JsonRpcTransportPeer {
     this.notificationHandler = handler
   }
 
-  request(method: string, params: Record<string, unknown>): Promise<unknown> {
+  /**
+   * Send a request and await its response.
+   * @param method - the JSON-RPC method name.
+   * @param params - the request parameters object.
+   * @param signal - optional abandonment signal: aborting removes the pending
+   * entry (no state is retained for a response that may never come) and
+   * rejects with the signal's reason.
+   * @returns the result; rejects per {@link JsonRpcTransportPeer.request}.
+   */
+  request(method: string, params: object, signal?: AbortSignal): Promise<unknown> {
     const id = `req_${randomUUID().replaceAll('-', '')}`
     const message = { jsonrpc: '2.0', id, method, params }
     return new Promise((resolve, reject) => {
-      this.pending.set(id, { resolve, reject })
+      let detach = (): void => {}
+      if (signal !== undefined) {
+        if (signal.aborted) {
+          reject(abortError(signal.reason))
+          return
+        }
+        const onAbort = (): void => {
+          this.pending.delete(id)
+          reject(abortError(signal.reason))
+        }
+        signal.addEventListener('abort', onAbort, { once: true })
+        detach = () => { signal.removeEventListener('abort', onAbort) }
+      }
+      this.pending.set(id, {
+        resolve: (value) => {
+          detach()
+          resolve(value)
+        },
+        reject: (error) => {
+          detach()
+          reject(error)
+        },
+      })
       try {
         this.write(message)
       } catch (error) {
         this.pending.delete(id)
+        detach()
         reject(error instanceof Error ? error : new Error(String(error)))
       }
     })
   }
 
-  notify(method: string, params?: Record<string, unknown>): void {
+  notify(method: string, params?: object): void {
     this.write(params === undefined ? { jsonrpc: '2.0', method } : { jsonrpc: '2.0', method, params })
   }
 
@@ -196,7 +243,11 @@ export class JsonRpcLineTransport implements JsonRpcTransportPeer {
     this.pending.delete(id)
     if (frame.error && typeof frame.error === 'object') {
       const error = frame.error as Record<string, unknown>
-      pending.reject(new Error(typeof error.message === 'string' ? error.message : 'JSON-RPC error'))
+      pending.reject(new JsonRpcResponseError(
+        typeof error.code === 'number' ? error.code : undefined,
+        typeof error.message === 'string' ? error.message : 'JSON-RPC error',
+        error.data,
+      ))
       return
     }
     pending.resolve(frame.result)
@@ -221,3 +272,8 @@ export class JsonRpcLineTransport implements JsonRpcTransportPeer {
 function objectParams(params: unknown): Record<string, unknown> {
   return params && typeof params === 'object' && !Array.isArray(params) ? params as Record<string, unknown> : {}
 }
+
+/** Normalize an abort reason into the rejection Error (a non-Error reason is stringified). */
+function abortError(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(`JSON-RPC request aborted: ${String(reason)}`)
+}

packages/sdk/sdk-protocol/src/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Named wire types for the DeepSeek Harness SDK runtime protocol: the three
+ * request/result pairs and the four server-to-client notification payloads
+ * exchanged over the newline-delimited JSON-RPC stdio transport. The server
+ * plugin (`@deepseek-ai/dsh-jsonrpc`) and SDK clients share these shapes;
+ * `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`.
+ *
+ * @module @deepseek-ai/dsh-sdk-protocol/types
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SubagentStopReason } from '@deepseek-ai/dsh-subagent'
+
+/** Parameters for the process-wide SDK handshake. */
+export interface InitializeParams {
+  /** Working directory recorded on every SDK-created session's header. */
+  cwd: string
+  /** Provider route every SDK-created agent runs on. */
+  provider: string
+  /** Model name every SDK-created agent runs on (the server may mount a fallback adapter; see `HarnessSdkServer.initialize`). */
+  model: string
+}
+
+/** Wire-stable server identity returned by initialization. */
+export interface InitializeResult {
+  /** Wire-stable server identity (`deepseek-harness-sdk-runtime`) and version. */
+  serverInfo: { name: string; version: string }
+}
+
+/** One user turn on one SDK session. */
+export interface SessionPromptParams {
+  /** The SDK-side session id; an unknown id lazily creates the agent+session pair. */
+  sessionId: string
+  /** The prompt content blocks, sent verbatim as the user message. */
+  contentBlocks: ContentBlock[]
+}
+
+/** Prompt acceptance after turn settlement; outcome rides on `session.finished`. */
+export interface SessionPromptResult {
+  /** Always `true`; the turn outcome is the paired `session.finished` notification. */
+  accepted: true
+}
+
+/** Deployment-mapped SDK outcome: `ok` for an accepted result, `error` otherwise. */
+export type SdkRunStatus = 'ok' | 'error'
+
+/** `session.event` payload: one session-log event, streamed as it is recorded. */
+export interface SessionEventNotification {
+  /** Session the event belongs to (every session in the runtime, not only SDK-created ones). */
+  sessionId: string
+  /** The full session-log event envelope. */
+  event: SessionEvent
+}
+
+/** `session.finished` payload: one per accepted prompt, after turn settlement. */
+export interface SessionFinishedNotification {
+  /** The settled session. */
+  sessionId: string
+  /** Deployment-mapped turn outcome (see `maxTokensAsSuccess` on the server). */
+  status: SdkRunStatus
+  /** Why the last message-triggered turn ended; absent when no turn ran. */
+  reason: TurnEndReason | undefined
+}
+
+/** `subagent.started` payload: an in-runtime child session was created. */
+export interface SubagentStartedNotification {
+  /** The delegating session. */
+  parentSessionId: string
+  /** The new child session. */
+  childSessionId: string
+}
+
+/** `subagent.finished` payload: an in-process subagent run ended (remote runs are not reported). */
+export interface SubagentFinishedNotification {
+  /** Subagent provider name that ran the child. */
+  provider: string
+  /** The child agent's id (equals {@link childSessionId} for local runs). */
+  agentId: string
+  /** The delegating session. */
+  parentSessionId: string
+  /** The child session. */
+  childSessionId: string
+  /** Deployment-mapped run outcome. */
+  status: SdkRunStatus
+  /** The provider-reported stop reason. */
+  stopReason: SubagentStopReason
+  /** The child's final assistant message, when it produced one. */
+  lastAssistantMessage?: ContentBlock[]
+}
+
+/** Server-to-client notifications by JSON-RPC method name. */
+export interface HarnessSdkNotificationMap {
+  'session.event': SessionEventNotification
+  'session.finished': SessionFinishedNotification
+  'subagent.started': SubagentStartedNotification
+  'subagent.finished': SubagentFinishedNotification
+}
+
+/** Client-to-server request methods with their param and result shapes. */
+export interface HarnessSdkRequestMap {
+  'initialize': { params: InitializeParams; result: InitializeResult }
+  'session/prompt': { params: SessionPromptParams; result: SessionPromptResult }
+  'shutdown': { params: undefined; result: Record<string, never> }
+}

packages/sdk/sdk-protocol/tests/transport.spec.ts

@@ -1,7 +1,7 @@
 import { once } from 'node:events'
 import { PassThrough, Writable } from 'node:stream'
 import { describe, expect, it } from 'vitest'
-import { JsonRpcLineTransport } from '../src/index.ts'
+import { JsonRpcLineTransport, JsonRpcResponseError } from '../src/index.ts'
 
 function transportPair() {
   const aToB = new PassThrough()
@@ -41,7 +41,7 @@ describe('JsonRpcLineTransport', () => {
     b.close()
   })
 
-  it('reports JSON-RPC request errors from the remote peer', async () => {
+  it('reports JSON-RPC request errors from the remote peer with their wire code', async () => {
     const { a, b } = transportPair()
     a.onRequest(async () => {
       throw new Error('handler boom')
@@ -49,12 +49,59 @@ describe('JsonRpcLineTransport', () => {
     a.start()
     b.start()
 
-    await expect(b.request('explode', {})).rejects.toThrow('handler boom')
+    const failure = await b.request('explode', {}).then(
+      () => { throw new Error('request unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(failure).toBeInstanceOf(JsonRpcResponseError)
+    expect(failure).toMatchObject({ message: 'handler boom', code: -32603, data: undefined })
 
     a.close()
     b.close()
   })
 
+  it('rejects immediately on a pre-aborted signal without registering pending state', async () => {
+    const { b } = transportPair()
+    b.start()
+    const controller = new AbortController()
+    controller.abort(new Error('already gone'))
+    await expect(b.request('never-sent', {}, controller.signal)).rejects.toThrow('already gone')
+    expect((b as unknown as { pending: Map<string, unknown> }).pending.size).toBe(0)
+    b.close()
+  })
+
+  it('abandons a pending request on abort, stringifying a non-Error reason', async () => {
+    const { b } = transportPair()
+    b.start()
+    const controller = new AbortController()
+    const pending = b.request('never-answered', {}, controller.signal)
+    controller.abort('plain-string-reason')
+    await expect(pending).rejects.toThrow('JSON-RPC request aborted: plain-string-reason')
+    // The abandonment removed the pending entry — nothing is retained for a
+    // response that may never come.
+    expect((b as unknown as { pending: Map<string, unknown> }).pending.size).toBe(0)
+    b.close()
+  })
+
+  it('preserves structured error data from an error response frame', async () => {
+    const { aToB, bToA, b } = transportPair()
+    b.start()
+
+    const pending = b.request('remote-error-data', {})
+    const requestChunk = (await once(bToA, 'data'))[0] as Buffer | string
+    const request = JSON.parse(String(requestChunk)) as { id: string }
+    aToB.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: 7, message: 'structured', data: { detail: 'x' } } })}\n`)
+
+    const failure = await pending.then(
+      () => { throw new Error('request unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(failure).toBeInstanceOf(JsonRpcResponseError)
+    expect(failure).toMatchObject({ code: 7, message: 'structured', data: { detail: 'x' } })
+
+    b.close()
+  })
+
   it('stringifies non-Error request handler failures', async () => {
     const { a, b } = transportPair()
     a.onRequest(async () => {

packages/sdk/sdk-protocol/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../subagent/subagent"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/subagent/README.i18n.yaml

@@ -1,6 +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
-README.md: 8414836efd756f60258566ae3e4e00de2d4110d7
-README.zh.md: d32228495cd6c57398c88cea92ce168ecf278188
+#   pnpm run verify-translation-pairing --write packages/subagent/README.md
+README.md: fed0c3d6b252f5eeb8355c3b544066765999120a
+README.zh.md: 45f3c83f57613c16ba00063c9da9ac720a57727e

packages/subagent/README.md

@@ -11,8 +11,9 @@ The subagent seam: an agent delegating work to a child agent. Like the [bash](..
 | `subagent-spawn/` | In-process backend: a fresh child agent | (registers on `ctx.subagents`) |
 | `subagent-fork/` | In-process backend: a child seeded with the parent's completed-turn prefix | (registers on `ctx.subagents`) |
 | `subagent-acp/` | Out-of-process backend: a child agent in a spawned subprocess, driven over ACP | (registers on `ctx.subagents`) |
+| `subagent-dsh-sdk/` | Out-of-process backend: a child harness runtime in a spawned subprocess, driven over stdio JSON-RPC through the TypeScript SDK client | (registers on `ctx.subagents`) |
 | `tool-subagent/` | Model-facing `subagent` delegation tool over `ctx.subagents` | (registers on `ctx.tools`) |
 
-The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a library with no provider of its own — both depend on it, neither on the other), and the out-of-process `subagent-acp` backend spawns its child through the [`subprocess/`](../subprocess/README.md) seam (the shared credential scrub, tree-scoped teardown, and dispose ladder). Tests replace only the child boundary with package-local fixtures.
+The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a library with no provider of its own — both depend on it, neither on the other), and the out-of-process `subagent-acp` / `subagent-dsh-sdk` backends spawn their children through the [`subprocess/`](../subprocess/README.md) seam (the shared credential scrub, tree-scoped teardown, and dispose ladder). Tests replace only the child boundary with package-local fixtures.
 
 The proposal and design rationale: [.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md).

packages/subagent/README.zh.md

@@ -11,8 +11,9 @@ subagent seam 允许 agent（智能体）把工作委派给子 agent。与 [bash
 | `subagent-spawn/` | 进程内后端：全新的子 agent | （注册到 `ctx.subagents`） |
 | `subagent-fork/` | 进程内后端：以父 agent 已完成轮次的前缀作为初始内容的子 agent | （注册到 `ctx.subagents`） |
 | `subagent-acp/` | 进程外后端：在派生子进程中运行并通过 ACP（Agent Client Protocol）驱动的子 agent | （注册到 `ctx.subagents`） |
+| `subagent-dsh-sdk/` | 进程外后端：在派生子进程中运行的子 harness 运行时，经 TypeScript SDK 客户端走 stdio JSON-RPC 驱动 | （注册到 `ctx.subagents`） |
 | `tool-subagent/` | 面向模型的 `subagent` 委派工具，基于 `ctx.subagents` | （注册到 `ctx.tools`） |
 
-接口位于 `subagent/subagent/`。进程内 `subagent-spawn` / `subagent-fork` 后端共享 `subagent-inprocess` 驱动器（一个自身不提供提供方的库：两者都依赖它，彼此不依赖），进程外 `subagent-acp` 后端则经由 [`subprocess/`](../subprocess/README.md) seam spawn 其子进程（共享的凭据清除、以进程树为范围的拆卸、dispose（资源释放）阶梯）。测试只用包内 fixture（测试前置数据）替换子 agent 边界。
+接口位于 `subagent/subagent/`。进程内 `subagent-spawn` / `subagent-fork` 后端共享 `subagent-inprocess` 驱动器（一个自身不提供提供方的库：两者都依赖它，彼此不依赖），进程外 `subagent-acp` / `subagent-dsh-sdk` 后端则经由 [`subprocess/`](../subprocess/README.md) seam spawn 其子进程（共享的凭据清除、以进程树为范围的拆卸、dispose（资源释放）阶梯）。测试只用包内 fixture（测试前置数据）替换子 agent 边界。
 
 提案与设计理由见 [.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)。

packages/subagent/subagent-dsh-sdk/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: 95ddd154c8262e8854280e74618bdd9be9c938c0
+README.zh.md: c10145f34cd785d10f4b660a5f6414455ad42464

packages/subagent/subagent-dsh-sdk/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](../../sdk/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.
+
+## 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) 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 runs one SDK turn and reads the child's answer from its session events: the last complete `assistant/message`, or the `text-delta` stream accumulated so far when the turn 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 child reports its turn outcome as a structured `TurnEndReason` on `session.finished`; the provider maps it into the seam vocabulary. `completed` → `completed`, `max-tokens` → `max-tokens`, `aborted` → `aborted`; everything else — `error`, `interrupted`, `disposed`, a future variant, or a turn that never ran — 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` | Provider route sent in the child's `initialize`. |
+| `model` | `deepseek-v4-flash` | Model sent in the child's `initialize`. |
+| `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']
+    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).
+
+Keyless tests drive the SDK client package's scripted fake runtime over real stdio, including a Loader-composed e2e where the child is a real second harness runtime proving parent-session cwd inheritance end to end (`tests/loader-composition.e2e.ts`).
+
+## 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.

packages/subagent/subagent-dsh-sdk/README.zh.md

@@ -0,0 +1,97 @@
+# @deepseek-ai/dsh-subagent-dsh-sdk
+
+[English](README.md) | 中文
+
+SDK provider 把每个子代理作为一个完整的 DeepSeek Harness 运行时跑在全新子进程里，经由 [TypeScript SDK 客户端](../../sdk/sdk-client/README.md)走 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在线协议与子进程契约：ACP 后端能驱动任何 Agent Client Protocol 代理；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包可执行文件），因此子进程是一个完整的对等 harness——自有 `cordis.yml` 决定的组成、会话持久化、模型路由与工具。
+
+## 启动与所有权
+
+`start(request)` 先解析子进程工作目录，经 `DeepSeekHarness` 生成运行时，并在履行前完成 `initialize` 握手（携带配置的 `provider`/`model` 路由）。因此履行意味着子运行时已就绪、所有权已移交调用方。生成、握手或发布前取消的失败只在子进程被收割之后拒绝；工作目录解析失败在生成任何东西之前拒绝。
+
+工作目录的解析与 ACP 后端完全一致，经由接缝共享的进程外助手（[`dsh-subagent`](../subagent/README.md)）：设置了 `cwd` 覆盖则用之（加载时校验一次），否则用发起委托的父会话 cwd——绝不用服务器进程自己的 cwd。解析出的路径同时成为子进程 cwd 与其 SDK 会话的工作区 cwd。
+
+返回的 run id 铸造于父命名空间；子运行时的会话 id 只存在于子进程内部。发布之后，provider 跑一个 SDK 回合，并从子会话事件中读取答案：最后一条完整 `assistant/message`，或回合被截断时已累积的 `text-delta` 流——部分答案在取消与错误路径上都得以保留。
+
+`dispose()` 幂等：先把结果就地定格为 `aborted`（线上没有 prompt 取消方法），再关闭运行时——一次有界的协议 `shutdown` 请求，随后是共享的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出。
+
+## 停止原因映射
+
+子进程在 `session.finished` 上以结构化 `TurnEndReason` 报告回合结局；provider 把它映射进接缝词汇表。`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余一切——`error`、`interrupted`、`disposed`、未来变体、或根本没跑回合——映射为 `error`，不洁终止绝不报告为成功。发布后的传输层失败经 `onError` 诊断汇（接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；接缝契约禁止 `result` 拒绝。
+
+## 能力与上下文
+
+Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilter`/`persona` 全为 false），且 `inheritsParentContext: false`：子进程是另一进程里的全新运行时，唯一来自父方的输入是工作区 cwd。基于本 provider 的 `dsh-tool-subagent` 部署应设置 `maxDepth: 'provider-managed'`——子 harness 拥有自己的递归预算。
+
+## 配置
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `providerName` | `dsh-sdk` | `ctx.subagents` 上的注册名。 |
+| `command` | 必填 | 每次 run 生成的可执行文件（子运行时 bin 或打包 exe）。 |
+| `args` | `[]` | 命令参数（通常是子进程的 `cordis.yml` 路径）。 |
+| `cwd` | 父会话 cwd | 工作目录覆盖；校验规则与 [`subagent-acp`](../subagent-acp/README.md) 相同。 |
+| `provider` | `deepseek` | 写入子进程 `initialize` 的 provider 路由。 |
+| `model` | `deepseek-v4-flash` | 写入子进程 `initialize` 的模型。 |
+| `env` | `{}` | 在凭据擦除后的父环境之上叠加的显式子环境（例如子进程自己的 `DEEPSEEK_API_KEY`，或 `DSH_CORDIS_CONFIG`）。 |
+| `shutdownTimeoutMs` | `1000` | 处置期间协议 `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']
+    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) 接缝的 `scrubbedParentEnv()` 为基底——移除形似凭据与 `DSH_*` 的环境变量——再在擦除之后合并显式 `config.env` 值。子进程由 SDK 客户端生成而非经 `ctx.subprocess`（subprocess README 记载的 SDK 托管传输例外），因此本后端自行应用该擦除。JSON-RPC 线就是真实的序列化边界。
+
+本包没有默认导出。否则 Cordis loader 解包会隐藏具名 `inject` 元数据；见[事后分析 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
+
+免密钥测试通过真实 stdio 驱动 SDK 客户端包的脚本化伪运行时，还包括一个 Loader 组合 e2e：子进程是真实的第二个 harness 运行时，端到端证明父会话 cwd 继承（`tests/loader-composition.e2e.ts`）。
+
+## Model Experience
+
+### Child-agent request
+
+#### What the model sees
+
+子运行时的模型收到独立任务作为其用户消息，加上该运行时自己配置的系统提示、工具与全新会话。它收不到任何父对话。本 provider 不宣告可选启动期能力，因此本地服务会拒绝需要 persona、工具过滤、深度强制或结构化输出的请求，而不是静默省略。
+
+#### Token effect
+
+子进程支付一份独立的完整上下文与自己的多步历史。这些 token 绝不进入父上下文。
+
+#### KV Cache effect
+
+独立于父请求缓存。每个 SDK 子进程只能复用在其自身 provider、模型、组成与历史下完全相同的前缀；子步骤在此之外只增不改。
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+经由 `dsh-tool-subagent`，父方只收到子进程的最终助手文本（或累积的部分文本），或该消费者精确的停止原因错误——收不到中间消息与工具流量。
+
+#### Token effect
+
+父输入只增长最终结果或错误，其大小依数据而定，保留至压缩。本 provider 自身不给父方增加任何 schema。
+
+#### KV Cache effect
+
+只追加；新可见内容跟在可复用请求前缀之后，不使既有 KV 缓存条目失效。
+
+## Known Limitations and Deferred Work
+
+- **每次 run 一个全新运行时进程** —— 无池化；harness 运行时要启动完整插件树，单次生成成本高于 ACP 后端的典型子进程。
+- **无可选启动期能力** —— 父方无法在子进程内强制 `outputSchema`、深度、工具过滤或 persona；请改为配置子进程自己的 `cordis.yml`。
+- **子进程的转录留在其自己的会话根** —— 父日志只记录委托工具调用/结果（接缝的子隔离规则）；流式 `session.event` 通道只用于提取输出，不桥接进父日志。
+- **仅限本地子进程** —— 解析出的 cwd 是本地路径；远程运行时需要自己的后端。

packages/subagent/subagent-dsh-sdk/package.json

@@ -0,0 +1,55 @@
+{
+  "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",
+  "private": true,
+  "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",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-sdk-client": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-sdk-client": "workspace:^",
+    "@deepseek-ai/dsh-sdk-protocol": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/subagent/subagent-dsh-sdk/src/index.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 'cordis'
+import z from 'schemastery'
+import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+import { assertPositiveFinite, NO_START_CAPABILITIES, resolveChildCwd, validateConfiguredCwd } from '@deepseek-ai/dsh-subagent'
+import {
+  DEFAULT_DISPOSE_EOF_GRACE_MS,
+  DEFAULT_DISPOSE_GRACE_MS,
+  DEFAULT_SHUTDOWN_TIMEOUT_MS,
+  startSdkRun,
+  type SdkRunSpec,
+} from './run.ts'
+
+export const name = 'subagent-dsh-sdk'
+export const inject = ['subagents']
+
+/** 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`). */
+  provider: string
+  /** Model the child runtime initializes with (default `deepseek-v4-flash`). */
+  model: string
+  /**
+   * 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 const Config: z<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'),
+  model: z.string().default('deepseek-v4-flash'),
+  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 shape after schemastery applied the defaults (cwd has none). */
+type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>
+
+/**
+ * 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).
+ */
+class SdkProvider implements SubagentProvider {
+  readonly capabilities: SubagentCapabilities = NO_START_CAPABILITIES
+  // Context contract: an out-of-process SDK child starts fresh — no parent conversation crosses the process boundary.
+  readonly inheritsParentContext = false
+
+  constructor(readonly name: string, private readonly ctx: Context, private readonly config: ResolvedConfig) {}
+
+  start(request: SubagentStartRequest) {
+    const spec: SdkRunSpec = {
+      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,
+      env: this.config.env,
+      shutdownTimeoutMs: this.config.shutdownTimeoutMs,
+      disposeEofGraceMs: this.config.disposeEofGraceMs,
+      disposeGraceMs: this.config.disposeGraceMs,
+      onError: (error, stopReason) => {
+        // The seam forbids `result` rejecting, so a child-level failure is
+        // flattened to a stop reason — preserve it here rather than losing it.
+        this.ctx.logger.warn(`subagent-dsh-sdk "${this.name}": child run failed (${stopReason}): ${error.message}`)
+      },
+    }
+    return startSdkRun(request, spec)
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  // schemastery (Config) has already filled every defaulted field.
+  const resolved = config as ResolvedConfig
+  assertPositiveFinite('subagent-dsh-sdk', 'shutdownTimeoutMs', resolved.shutdownTimeoutMs)
+  assertPositiveFinite('subagent-dsh-sdk', 'disposeEofGraceMs', resolved.disposeEofGraceMs)
+  assertPositiveFinite('subagent-dsh-sdk', 'disposeGraceMs', resolved.disposeGraceMs)
+  // Interpret a relative configured cwd against the harness launch directory
+  // ONCE, at load, and fail a misconfigured directory here — not per start.
+  const configuredCwd = validateConfiguredCwd('subagent-dsh-sdk', resolved.cwd)
+  const validated: ResolvedConfig = configuredCwd === undefined
+    ? resolved
+    : { ...resolved, cwd: configuredCwd }
+  ctx.subagents.registerProvider(new SdkProvider(validated.providerName, ctx, validated))
+}

packages/subagent/subagent-dsh-sdk/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-dsh-sdk`.
+ * @module @deepseek-ai/dsh-subagent-dsh-sdk/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-dsh-sdk'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-dsh-sdk-invariant'
+/** Service required before the companion can reserve package ownership. */
+export 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: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/subagent/subagent-dsh-sdk/src/run.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 { randomUUID } from 'node:crypto'
+import { DeepSeekHarness, type HarnessNotification } from '@deepseek-ai/dsh-sdk-client'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent'
+import { settleRunResult, subprocessRunHandle } from '@deepseek-ai/dsh-subagent'
+import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
+
+/** 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
+  /**
+   * 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 const DEFAULT_DISPOSE_EOF_GRACE_MS = 6_000
+
+/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
+export const DEFAULT_DISPOSE_GRACE_MS = 3_000
+
+/** Default bound on the protocol `shutdown` exchange during dispose. */
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1_000
+
+/**
+ * Map a child turn-end reason to a harness {@link SubagentStopReason}.
+ * @param reason - the `session.finished` reason, or `undefined` when the
+ * child 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 function sdkStopReason(reason: TurnEndReason | undefined): SubagentStopReason {
+  switch (reason?.kind) {
+    case 'completed':
+      return 'completed'
+    case 'max-tokens':
+      return 'max-tokens'
+    case 'aborted':
+      return 'aborted'
+    // error / interrupted / disposed / a future merged variant /
+    // no turn at all: the task did NOT finish cleanly — surface a generic
+    // failure so the consumer maps it to an isError result.
+    default:
+      return 'error'
+  }
+}
+
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value: unknown): Error {
+  // The catch only sees rejections from the SDK client, which are always
+  // `Error`s; the `String(value)` arm is a defensive fallback for a non-Error
+  // throw that the typed surfaces cannot produce.
+  /* 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.
+ */
+export async function startSdkRun(request: SubagentStartRequest, spec: SdkRunSpec): Promise<SubagentRun> {
+  if (request.signal.aborted) throw new Error('subagent request was aborted before the SDK child started')
+  // The run id lives in the parent namespace; the child runtime's session id
+  // (minted below, private to the wire) exists only inside the child process.
+  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,
+  })
+
+  // Cancellation settles the result without waiting for a cooperative child.
+  const flags = { cancelled: false }
+  let signalCancelSettled!: () => void
+  const cancelSettled = new Promise<void>((resolve) => { signalCancelSettled = resolve })
+  const requestCancel = (): void => {
+    if (flags.cancelled) return
+    flags.cancelled = true
+    signalCancelSettled()
+  }
+  const onAbort = (): void => { requestCancel() }
+  request.signal.addEventListener('abort', onAbort, { once: true })
+
+  // Establish the child handshake before publishing a handle. Any failure
+  // owns the still-private process and reaps it before rejecting.
+  try {
+    await Promise.race([
+      harness.start(),
+      cancelSettled.then((): never => { throw new Error('subagent cancelled before the SDK child initialized') }),
+    ])
+    // Defensive: an abort() is a macrotask and no user callback runs inside
+    // the microtask drain between handshake fulfillment and this continuation,
+    // so the recheck is not schedulable today; it guards future reentrancy.
+    /* v8 ignore next */
+    if (flags.cancelled) throw new Error('subagent cancelled before the SDK child initialized')
+  } catch (error: unknown) {
+    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('-', '')}`
+  // The child's final answer: the last complete assistant message when one
+  // exists, else the text streamed so far (a partial answer surviving cancel).
+  let lastMessage: ContentBlock[] | undefined
+  const partial: string[] = []
+  const observe = (notification: HarnessNotification): void => {
+    if (notification.method !== 'session.event' || notification.params.sessionId !== childSessionId) return
+    const event = notification.params.event as SessionEvent
+    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.content
+    }
+  }
+  const collectOutput = (): ContentBlock[] => {
+    if (lastMessage !== undefined) return lastMessage
+    const text = partial.join('')
+    return text.length > 0 ? [{ type: 'text', text }] : []
+  }
+
+  // Race the child turn against local cancellation; the shared settlement
+  // flattens failures under the seam's never-reject contract.
+  const result: Promise<SubagentResult> = settleRunResult({
+    attempt: async () => {
+      const turn = await Promise.race([
+        harness.session(childSessionId).run(request.prompt, { onNotification: observe }),
+        cancelSettled.then(() => 'cancelled' as const),
+      ])
+      if (turn === 'cancelled') return { output: collectOutput(), stopReason: 'aborted' }
+      return { output: collectOutput(), stopReason: sdkStopReason(turn.reason) }
+    },
+    collectOutput,
+    cancelled: () => flags.cancelled,
+    onError: spec.onError,
+    signal: request.signal,
+    onAbort,
+  })
+
+  // There is no wire-level prompt cancel: dispose settles the result locally,
+  // then the bounded shutdown request + dispose ladder tears the child down.
+  return subprocessRunHandle({
+    id,
+    result,
+    signal: request.signal,
+    onAbort,
+    requestCancel,
+    teardown: () => harness.close(),
+  })
+}

packages/subagent/subagent-dsh-sdk/tests/loader-composition.e2e.ts

@@ -0,0 +1,107 @@
+/**
+ * Keyless REAL-composition coverage for parent-session cwd inheritance across
+ * the SDK wire: a test-only cordis.yml boots the headless app through the
+ * Loader with the SDK backend's `cwd` omitted, a scripted model delegates
+ * once, and the child — a COMPLETE second harness runtime booted from its own
+ * cordis.yml and driven over stdio JSON-RPC — echoes where it actually ran.
+ * Both the parent's tool result and the child's own persisted session log
+ * must carry the parent session's cwd. Mock-only composition, so only this
+ * keyless tier applies (the with-key tier lives in subagent-sdk.e2e.ts).
+ */
+
+import { realpathSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { type SessionEvent } from '@deepseek-ai/dsh-session'
+import { resolveExampleLaunch, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+
+const fixtureDir = new URL('../../../../examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/', import.meta.url)
+const driver = fileURLToPath(new URL('driver.ts', fixtureDir))
+const configPath = fileURLToPath(new URL('cordis.yml', fixtureDir))
+const childConfigPath = fileURLToPath(new URL('child.cordis.yml', fixtureDir))
+const runtimeBin = fileURLToPath(new URL('../../../../packages/examples/jsonrpc-demo/src/bin.ts', import.meta.url))
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+async function jsonlFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const paths = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return jsonlFiles(path)
+    return entry.isFile() && entry.name.endsWith('.jsonl') ? [path] : []
+  }))
+  return paths.flat()
+}
+
+async function sessionEvents(log: string): Promise<SessionEvent[]> {
+  const lines = (await readFile(log, 'utf8')).trimEnd().split('\n')
+  return lines.slice(1).map(line => JSON.parse(line) as SessionEvent)
+}
+
+describe('SDK subagent cwd inheritance through a real cordis.yml', () => {
+  it('runs the child runtime in the parent session workspace', async () => {
+    // The child launch honors the same src/lib mode as the driving harness,
+    // per the shared example-launch resolver (testing policy forbids
+    // hand-written `--import tsx` argv for example subprocesses).
+    const childLaunch = resolveExampleLaunch({
+      srcBin: runtimeBin,
+      configArgs: [childConfigPath],
+      tsconfigPath: repoTsconfig,
+    })
+
+    let events: SessionEvent[] = []
+    let childEvents: SessionEvent[] = []
+    let workspace = ''
+    const { stderr } = await runLoaderSmoke({
+      label: 'dsh-sdk-subagent cwd composition smoke',
+      tempDirPrefix: 'dsh-sdk-subagent-cwd-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      // Two complete harness runtimes boot in sequence (driver, then the SDK
+      // child); from-source tsx boots under load need more than the default
+      // 30s window.
+      processTimeoutMs: 120_000,
+      env: {
+        DSH_TEST_CHILD_COMMAND: childLaunch.command,
+        DSH_TEST_CHILD_ARGS: JSON.stringify(childLaunch.args),
+        DSH_TEST_CHILD_ENV: JSON.stringify({
+          ...Object.fromEntries(Object.entries(childLaunch.env).filter(([, value]) => value !== undefined)),
+        }),
+      },
+      inspect: async (cwd) => {
+        // The child reports realpaths; canonicalize the temp workspace to match.
+        workspace = realpathSync(cwd)
+        const parentLogs = await jsonlFiles(join(cwd, '.sessions'))
+        expect(parentLogs).toHaveLength(1)
+        events = await sessionEvents(parentLogs[0] as string)
+        // The child runtime persisted its own transcript in ITS cwd — which
+        // must be the parent session's workspace for the inheritance to hold.
+        const childLogs = await jsonlFiles(join(cwd, '.child-sessions'))
+        expect(childLogs).toHaveLength(1)
+        childEvents = await sessionEvents(childLogs[0] as string)
+      },
+    })
+    expect(stderr).not.toContain('UNHANDLED')
+
+    // The parent's tool result carries the child model's echo of its real
+    // process.cwd() — the parent session's workspace, never the harness
+    // process's launch directory.
+    const results = events.filter(event => event.type === 'tool/result')
+    expect(results).toHaveLength(1)
+    const resultText = results[0]!.data.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    expect(resultText).toBe(`child cwd: ${workspace}`)
+
+    // The child ran a real turn of its own: user message in, assistant out.
+    expect(childEvents.some(event => event.type === 'user/message')).toBe(true)
+    const childAnswers = childEvents.filter(event => event.type === 'assistant/message')
+    expect(childAnswers.length).toBeGreaterThan(0)
+    // 15s of vitest headroom past the subprocess deadline, mirroring
+    // LOADER_SMOKE_TEST_TIMEOUT_MS's margin over the default window.
+  }, 135_000)
+})

packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts

@@ -0,0 +1,412 @@
+/**
+ * Keyless integration tests for the SDK subagent backend. Each spawns a REAL
+ * subprocess — the SDK client package's scripted fake runtime — and drives it
+ * through the REAL backend over real stdio JSON-RPC, so the handshake, the
+ * turn round-trip, stop-reason mapping, cancellation, env scrubbing, and
+ * quiescent disposal are all exercised end to end. No model, no key.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import * as sdk from '../src/index.ts'
+import {
+  DEFAULT_DISPOSE_EOF_GRACE_MS,
+  DEFAULT_DISPOSE_GRACE_MS,
+  DEFAULT_SHUTDOWN_TIMEOUT_MS,
+  sdkStopReason,
+  startSdkRun,
+  type SdkRunSpec,
+} from '../src/run.ts'
+
+const fakeRuntime = fileURLToPath(new URL('../../../sdk/sdk-client/tests/fake-runtime.ts', import.meta.url))
+
+/** A parent Agent stub. The SDK backend reads exactly one thing off it: the session header's cwd (the workspace its child inherits). */
+const fakeParent = { id: 'parent', session: { header: { cwd: process.cwd() } } } as unknown as Agent
+
+function request(text = 'p', signal = new AbortController().signal) {
+  return { prompt: [{ type: 'text' as const, text }], parent: fakeParent, signal }
+}
+
+/** Mount the SDK backend pointed at the fake runtime, scripted by `fakeEnv`. */
+async function setup(fakeEnv: Record<string, string> = {}, config: Partial<sdk.Config> = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SubagentService)
+  // The Config type models the post-validation shape, so the default registry
+  // name is stated here; the Loader-composition fixture omits providerName and
+  // exercises the schemastery default end to end.
+  await ctx.plugin(sdk, {
+    providerName: 'dsh-sdk',
+    command: process.execPath,
+    args: [fakeRuntime],
+    provider: 'fake-provider',
+    model: 'fake-model',
+    env: fakeEnv,
+    ...config,
+  })
+  return ctx
+}
+
+function text(blocks: { type: string; text?: string }[]): string {
+  return blocks.filter(b => b.type === 'text').map(b => b.text).join('')
+}
+
+/**
+ * Poll until `file` exists (the fake touches it once the probed state is
+ * reached), so cancel tests wait on a CONDITION rather than an arbitrary
+ * timeout. Fails loud if the child never signals readiness.
+ */
+async function waitForFile(file: string, timeoutMs = 5000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!existsSync(file)) {
+    if (Date.now() > deadline) throw new Error(`fake runtime never became ready (${file})`)
+    await new Promise(r => setTimeout(r, 10))
+  }
+}
+
+describe('sdkStopReason', () => {
+  it('maps each child turn-end reason to the harness vocabulary', () => {
+    expect(sdkStopReason({ kind: 'completed' })).toBe('completed')
+    expect(sdkStopReason({ kind: 'max-tokens' })).toBe('max-tokens')
+    expect(sdkStopReason({ kind: 'aborted' })).toBe('aborted')
+    expect(sdkStopReason({ kind: 'error', step: 0, message: 'x' })).toBe('error')
+    expect(sdkStopReason({ kind: 'interrupted' })).toBe('error')
+    expect(sdkStopReason({ kind: 'disposed' })).toBe('error')
+  })
+
+  it('treats an absent or unknown reason as an error', () => {
+    expect(sdkStopReason(undefined)).toBe('error')
+    expect(sdkStopReason({ kind: 'something-new' } as never)).toBe('error')
+  })
+})
+
+describe('dsh-subagent-dsh-sdk provider', () => {
+  it('runs a child turn end to end with a parent-unique run id', async () => {
+    const ctx = await setup({ FAKE_TEXT: 'hello from sdk child' })
+    const run = await ctx.subagents.start('dsh-sdk', request('do X'))
+    expect(run.localAgent).toBeUndefined()
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(text(result.output)).toBe('hello from sdk child')
+    // dispose is idempotent (one memoized teardown).
+    const disposal = run.dispose()
+    expect(run.dispose()).toBe(disposal)
+    await disposal
+
+    const nextRun = await ctx.subagents.start('dsh-sdk', request('again'))
+    expect(nextRun.id).not.toBe(run.id)
+    await nextRun.result
+    await nextRun.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('initializes the child with the configured provider/model and the parent cwd', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'subagent-dsh-sdk-init-'))
+    const recordFile = join(tmp, 'init.jsonl')
+    try {
+      const ctx = await setup({ FAKE_RECORD_INIT: recordFile })
+      const run = await ctx.subagents.start('dsh-sdk', request())
+      await run.result
+      await run.dispose()
+      const { readFileSync } = await import('node:fs')
+      const records = readFileSync(recordFile, 'utf8').trim().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+      expect(records).toEqual([{ cwd: process.cwd(), provider: 'fake-provider', model: 'fake-model' }])
+      await ctx.fiber.dispose()
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('scrubs ambient credentials but forwards explicit config env', async () => {
+    process.env.DSH_TEST_AMBIENT_SECRET_KEY = 'leak-me-not'
+    try {
+      const ctx = await setup({
+        FAKE_ECHO_ENV: 'DSH_TEST_AMBIENT_SECRET_KEY,DEEPSEEK_API_KEY',
+        DEEPSEEK_API_KEY: 'explicit-child-key',
+        FAKE_TEXT: 'done',
+      })
+      const run = await ctx.subagents.start('dsh-sdk', request())
+      const result = await run.result
+      const answer = text(result.output)
+      expect(answer).toContain('DSH_TEST_AMBIENT_SECRET_KEY=\n')
+      expect(answer).toContain('DEEPSEEK_API_KEY=explicit-child-key')
+      await run.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      delete process.env.DSH_TEST_AMBIENT_SECRET_KEY
+    }
+  })
+
+  it('maps a max-tokens child turn end', async () => {
+    const ctx = await setup({ FAKE_REASON_KIND: 'max-tokens', FAKE_STATUS: 'error' })
+    const run = await ctx.subagents.start('dsh-sdk', request())
+    expect((await run.result).stopReason).toBe('max-tokens')
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('flattens a child turn error into stopReason error and keeps partial text', async () => {
+    const ctx = await setup({ FAKE_REASON_KIND: 'error', FAKE_STATUS: 'error', FAKE_TEXT: 'partial answer' })
+    const run = await ctx.subagents.start('dsh-sdk', request())
+    const result = await run.result
+    expect(result.stopReason).toBe('error')
+    expect(text(result.output)).toBe('partial answer')
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('reports a settled-without-turn child as an error', async () => {
+    const ctx = await setup({ FAKE_REASON_KIND: 'none', FAKE_STATUS: 'error' })
+    const run = await ctx.subagents.start('dsh-sdk', request())
+    expect((await run.result).stopReason).toBe('error')
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('aborting the required signal settles a hung child as aborted', async () => {
+    const ctx = await setup({ FAKE_HANG_PROMPT: '1' }, { disposeEofGraceMs: 200, disposeGraceMs: 200 })
+    const controller = new AbortController()
+    const run = await ctx.subagents.start('dsh-sdk', request('p', controller.signal))
+    controller.abort('test')
+    const result = await run.result
+    expect(result.stopReason).toBe('aborted')
+    // The hung child streamed nothing, so the aborted result has no output.
+    expect(result.output).toEqual([])
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('cancelling between handshake and publish rejects start after reap', async () => {
+    // The abort lands while the child is INSIDE initialize (ready-file
+    // handshake window): the fake touches READY, we abort, then GO lets the
+    // handshake complete — so the post-race `flags.cancelled` recheck must
+    // reject even though the handshake itself succeeded.
+    const tmp = mkdtempSync(join(tmpdir(), 'subagent-dsh-sdk-midcancel-'))
+    const ready = join(tmp, 'ready')
+    const go = join(tmp, 'go')
+    try {
+      const controller = new AbortController()
+      const spec: SdkRunSpec = {
+        command: process.execPath,
+        args: [fakeRuntime],
+        cwd: process.cwd(),
+        provider: 'p',
+        model: 'm',
+        env: { FAKE_INIT_READY: ready, FAKE_INIT_GO: go },
+        shutdownTimeoutMs: 100,
+        disposeEofGraceMs: 200,
+        disposeGraceMs: 200,
+      }
+      const pending = startSdkRun(request('p', controller.signal), spec)
+      await waitForFile(ready)
+      controller.abort('mid-handshake')
+      const { writeFileSync } = await import('node:fs')
+      writeFileSync(go, 'go\n')
+      await expect(pending).rejects.toThrow('aborted before the SDK child started')
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps accumulated streamed text when the turn is cut short before a full message', async () => {
+    // The fake streams one text-delta chunk and then violates the protocol on
+    // the same pipe; frame order guarantees the chunk was dispatched before
+    // the failure settles, so the accumulated partial text (no complete
+    // assistant/message ever arrived) must survive into the error result.
+    const ctx = await setup({ FAKE_STREAM_THEN_MALFORMED: '1' }, { shutdownTimeoutMs: 100, disposeEofGraceMs: 200, disposeGraceMs: 200 })
+    const run = await ctx.subagents.start('dsh-sdk', request())
+    const result = await run.result
+    expect(result.stopReason).toBe('error')
+    expect(text(result.output)).toBe('streamed then cut short')
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('dispose cancels a hung child locally and reaps it', async () => {
+    const ctx = await setup({ FAKE_HANG_PROMPT: '1' }, { shutdownTimeoutMs: 100, disposeEofGraceMs: 200, disposeGraceMs: 200 })
+    const run = await ctx.subagents.start('dsh-sdk', request())
+    await run.dispose()
+    expect((await run.result).stopReason).toBe('aborted')
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects WITHOUT spawning when the signal is already aborted', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'subagent-dsh-sdk-preabort-'))
+    const sentinel = join(tmp, 'spawned')
+    try {
+      const controller = new AbortController()
+      controller.abort()
+      await expect(startSdkRun(
+        request('p', controller.signal),
+        // `touch <sentinel>` — runs only if the process is actually spawned.
+        {
+          command: 'touch',
+          args: [sentinel],
+          cwd: tmp,
+          provider: 'p',
+          model: 'm',
+          env: {},
+          shutdownTimeoutMs: DEFAULT_SHUTDOWN_TIMEOUT_MS,
+          disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS,
+          disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
+        },
+      )).rejects.toThrow('aborted before the SDK child started')
+      expect(existsSync(sentinel)).toBe(false)
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects after reaping when the child dies before the handshake', async () => {
+    const ctx = await setup({ FAKE_EXIT_BEFORE_INIT: '1', FAKE_STDERR: 'scripted boot failure' })
+    const failure = await ctx.subagents.start('dsh-sdk', request()).then(
+      () => { throw new Error('start unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(String(failure)).toContain('exit code: 3')
+    expect(String(failure)).toContain('scripted boot failure')
+    await ctx.fiber.dispose()
+  })
+
+  it('cancelling mid-handshake rejects start after reaping the child', async () => {
+    const controller = new AbortController()
+    const spec: SdkRunSpec = {
+      command: process.execPath,
+      args: [fakeRuntime],
+      cwd: process.cwd(),
+      provider: 'p',
+      model: 'm',
+      env: { FAKE_HANG_INIT: '1' },
+      shutdownTimeoutMs: 100,
+      disposeEofGraceMs: 200,
+      disposeGraceMs: 200,
+    }
+    const pending = startSdkRun(request('p', controller.signal), spec)
+    controller.abort('now')
+    await expect(pending).rejects.toThrow('aborted before the SDK child started')
+  })
+
+  it('routes a post-publication child failure through onError and settles error', async () => {
+    const seen: string[] = []
+    const spec: SdkRunSpec = {
+      command: process.execPath,
+      args: [fakeRuntime],
+      cwd: process.cwd(),
+      provider: 'p',
+      model: 'm',
+      // The fake dies as soon as the prompt arrives: FAKE_HANG_PROMPT plus a
+      // short-lived process is simulated by killing via dispose below instead;
+      // here use FAKE_MALFORMED to make the prompt reply violate the protocol.
+      env: { FAKE_MALFORMED_PROMPT: '1' },
+      shutdownTimeoutMs: 100,
+      disposeEofGraceMs: 200,
+      disposeGraceMs: 200,
+      onError: (error) => {
+        seen.push(error.message)
+        throw new Error('sink failure must be contained')
+      },
+    }
+    const run = await startSdkRun(request(), spec)
+    const result = await run.result
+    expect(result.stopReason).toBe('error')
+    expect(seen).toHaveLength(1)
+    await run.dispose()
+  })
+
+  it('routes provider-level onError through ctx.logger.warn', async () => {
+    const ctx = await setup({ FAKE_MALFORMED_PROMPT: '1' })
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+    const run = await ctx.subagents.start('dsh-sdk', request())
+    expect((await run.result).stopReason).toBe('error')
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('subagent-dsh-sdk "dsh-sdk": child run failed (error)')
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('registers under the configured provider name and unregisters on fiber dispose (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const fiber = await ctx.plugin(sdk, {
+      providerName: 'sdk-hmr',
+      command: process.execPath,
+      args: [fakeRuntime],
+      provider: 'p',
+      model: 'm',
+      env: {},
+    })
+    expect(ctx.subagents.getProvider('sdk-hmr')?.name).toBe('sdk-hmr')
+    expect(ctx.subagents.getProvider('sdk-hmr')?.inheritsParentContext).toBe(false)
+    expect(ctx.subagents.getProvider('sdk-hmr')?.capabilities).toEqual({
+      outputSchema: false,
+      depthLimit: false,
+      toolFilter: false,
+      persona: false,
+    })
+    await fiber.dispose()
+    expect(ctx.subagents.getProvider('sdk-hmr')).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects non-positive timing bounds at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const base = { providerName: 'sdk', command: 'true', args: [], provider: 'p', model: 'm', env: {} }
+    await expect(ctx.plugin(sdk, { ...base, shutdownTimeoutMs: 0 })).rejects.toThrow('shutdownTimeoutMs must be a positive finite number')
+    await expect(ctx.plugin(sdk, { ...base, disposeEofGraceMs: -1 })).rejects.toThrow('disposeEofGraceMs must be a positive finite number')
+    await expect(ctx.plugin(sdk, { ...base, disposeGraceMs: Number.NaN })).rejects.toThrow('disposeGraceMs must be a positive finite number')
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an empty config cwd at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await expect(ctx.plugin(sdk, {
+      providerName: 'sdk',
+      command: 'true',
+      args: [],
+      cwd: '',
+      provider: 'p',
+      model: 'm',
+      env: {},
+    })).rejects.toThrow('config cwd must not be empty')
+    await ctx.fiber.dispose()
+  })
+
+  it('uses a validated config cwd override instead of the parent session cwd', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'subagent-dsh-sdk-cwd-'))
+    try {
+      const ctx = await setup({ FAKE_ECHO_CWD: '1', FAKE_TEXT: 'done' }, { cwd: tmp })
+      const run = await ctx.subagents.start('dsh-sdk', request())
+      const result = await run.result
+      const { realpathSync } = await import('node:fs')
+      expect(text(result.output)).toContain(`cwd=${realpathSync(tmp)}`)
+      await run.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('fails loud when neither config cwd nor parent session cwd exists', async () => {
+    const ctx = await setup()
+    const parent = { id: 'parent', session: { header: {} } } as unknown as Agent
+    await expect(ctx.subagents.start('dsh-sdk', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal }))
+      .rejects.toThrow('no working directory for the child')
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps named plugin exports with no default export (loader shape)', () => {
+    expect(sdk.name).toBe('subagent-dsh-sdk')
+    expect(sdk.inject).toEqual(['subagents'])
+    expect(typeof sdk.apply).toBe('function')
+    expect(typeof sdk.Config).toBe('function')
+    expect((sdk as Record<string, unknown>).default).toBeUndefined()
+  })
+})

packages/subagent/subagent-dsh-sdk/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../sdk/sdk-client"
+    },
+    {
+      "path": "../../sdk/sdk-protocol"
+    },
+    {
+      "path": "../subagent"
+    },
+    {
+      "path": "../../support/loader-smoke"
+    },
+    {
+      "path": "../../subprocess/subprocess"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}