feat(web): add subagent conversation transport

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: 3c5a83a468b0cf9e596b8b13fafe40c409576fc5
-README.zh.md: f8533564575bf6b716f3fa7241ce47b8d4dd435f
+README.md: abca1e9b209891b152ff7f1a58fadb9f91e65839
+README.zh.md: dca3924af940a99fa99afb283f37a84570d1ad90

packages/host/apiproxy/README.md

@@ -36,6 +36,8 @@ The `command.*` and `skill.*` domains expose the host command registry and skill
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
+The `subagent.*` domain addresses continuable direct children by `{parentSessionId, childSessionId}`. `subagent.list` projects the durable continuable catalog plus an exact-live-parent hint from `ctx.subagents.listChildren`, excluding one-shot children; `subagent.history` verifies a healthy direct-child entry and reads its persisted log through `ctx.sessionQuery` without resuming an Agent. `subagent.prompt` requires that exact live parent, delivers human content through `ctx.subagents.followup()` with the request `rpcId` as attribution, and returns the accepted inbox `messageId`. Typed errors preserve catalog diagnostics, parent availability, resumability, authorization, and not-delivered distinctions without exposing the model-hidden continuation descriptor. See the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md).
+
 ## Carrier layer (`/client` + root)
 
 `AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.

packages/host/apiproxy/README.zh.md

@@ -36,6 +36,8 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表，以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；过期的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取：`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
+`subagent.*` 领域通过 `{parentSessionId, childSessionId}` 寻址可继续的直接 child。`subagent.list` 从 `ctx.subagents.listChildren` 投影持久化的可继续目录及确切 parent 是否存活的提示，并排除 one-shot child；`subagent.history` 先验证健康的直接 child 条目，再通过 `ctx.sessionQuery` 读取其持久化日志，且不恢复 Agent。`subagent.prompt` 要求该确切 parent 已存活，通过 `ctx.subagents.followup()` 投递用户内容，以请求 `rpcId` 作为来源信息，并返回已接纳消息的 inbox `messageId`。类型化错误保留目录诊断、parent 可用性、可恢复性、授权和未投递等区别，同时不暴露对模型隐藏的继续执行描述符。见 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md)。
+
 ## 载体层（`/client` + 根路径）
 
 `AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh -p` headless 模式使用。

packages/host/apiproxy/package.json

@@ -56,6 +56,7 @@
     "@deepseek-ai/dsh-session-title": "workspace:^",
     "@deepseek-ai/dsh-settings": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",

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

@@ -28,7 +28,8 @@ import type {} from '@deepseek-ai/dsh-tools'
 import type {
   ApiProxy, CredentialView, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup,
   ModelReasoning, MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSearchItem,
-  SessionSummary, SettingsNamespaceView, ToolEventView, WorkspaceId, WorkspaceView,
+  SessionSummary, SettingsNamespaceView, SubagentListEntry as SubagentCatalogEntry, ToolEventView,
+  WorkspaceId, WorkspaceView,
 } from './api/index.ts'
 import {
   SESSION_SEARCH_RESULT_LIMIT,
@@ -68,6 +69,8 @@ import type {
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
 import { openNativePath } from './native-path-opener.ts'
+import { SubagentError } from '@deepseek-ai/dsh-subagent'
+import type { SubagentListEntry as CoreSubagentListEntry } from '@deepseek-ai/dsh-subagent'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -462,6 +465,109 @@ function backscanArgs(events: readonly SessionEvent[], callId: string): { name:
   return undefined
 }
 
+/** Render one detached history page through the same presenter path as ordinary history. */
+function historyPage(
+  ctx: Context,
+  events: readonly SessionEvent[],
+  beforeSeq: number | undefined,
+  maxMessages: number | undefined,
+): { events: HistoryEntry[]; hasMore: boolean } {
+  const page = paginate(events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
+  return {
+    events: page.events.map((event) => {
+      const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
+      return { event, ...view === undefined ? {} : { view } }
+    }),
+    hasMore: page.hasMore,
+  }
+}
+
+/** Map a continuation failure without exposing descriptor or provider details. */
+function subagentPromptError(
+  request: RpcRequest<{ childSessionId: SessionId }>,
+  error: unknown,
+  signal?: AbortSignal,
+): RpcResponse<never> {
+  const childSessionId = request.payload.childSessionId
+  if (signal?.aborted) {
+    return err(request, { code: 'cancelled', message: 'subagent prompt was cancelled', details: {} })
+  }
+  if (error instanceof SubagentError) {
+    switch (error.code) {
+      case 'NOT_RESUMABLE':
+        return err(request, { code: 'subagent-not-resumable', message: 'subagent cannot be resumed', details: { childSessionId } })
+      case 'UNAUTHORIZED':
+        return err(request, { code: 'subagent-unauthorized', message: 'subagent does not belong to this parent', details: { childSessionId } })
+      case 'ACTIVATION_CLOSING':
+      case 'DRAINING':
+        return err(request, { code: 'subagent-not-delivered', message: 'message was not delivered', details: { childSessionId } })
+      default:
+        break
+    }
+  }
+  return err(request, { code: 'internal', message: 'subagent prompt failed', details: {} })
+}
+
+/** Verify one address against the complete durable direct-child catalog. */
+async function healthyCatalogChild(
+  ctx: Context,
+  parentSessionId: SessionId,
+  childSessionId: SessionId,
+  signal?: AbortSignal,
+): Promise<{ error?: RpcError }> {
+  try {
+    const entries = await ctx.subagents.listChildren(parentSessionId, signal)
+    const entry = entries.find(candidate => candidate.id === childSessionId)
+    if (entry === undefined || (entry.kind === 'child' && entry.mode !== 'continuable')) {
+      return {
+        error: {
+          code: 'subagent-not-found',
+          message: `session "${childSessionId}" is not a continuable direct child of "${parentSessionId}"`,
+          details: { parentSessionId, childSessionId },
+        },
+      }
+    }
+    if (entry.kind === 'diagnostic') {
+      return {
+        error: {
+          code: 'subagent-catalog-diagnostic',
+          message: `subagent "${childSessionId}" is ${entry.reason}`,
+          details: { parentSessionId, childSessionId, reason: entry.reason },
+        },
+      }
+    }
+    return {}
+  } catch (error: unknown) {
+    if (error instanceof SubagentError && error.code === 'CANCELLED') {
+      return { error: { code: 'cancelled', message: 'subagent catalog read was cancelled', details: {} } }
+    }
+    if (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
+      return {
+        error: {
+          code: 'subagent-not-found',
+          message: `parent session "${parentSessionId}" is unavailable`,
+          details: { parentSessionId, childSessionId },
+        },
+      }
+    }
+    return { error: { code: 'internal', message: 'subagent catalog read failed', details: {} } }
+  }
+}
+
+/** Project the durable catalog onto the continuable-only browser surface. */
+function continuableCatalog(entries: readonly CoreSubagentListEntry[]): SubagentCatalogEntry[] {
+  return entries.flatMap((entry): SubagentCatalogEntry[] => {
+    if (entry.kind === 'diagnostic') return [entry]
+    if (entry.mode !== 'continuable') return []
+    return [{
+      kind: 'child',
+      id: entry.id,
+      label: entry.label,
+      activity: entry.activity,
+    }]
+  })
+}
+
 /**
  * The projection baseline for one history tail page: the registry's
  * watermark-cache snapshot — one fully synchronous read (no await between the
@@ -1390,19 +1496,12 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         if ('error' in found) return err(request, found.error)
         // Everything below the resume above is synchronous: the page slice,
         // the seq read, and the projection walk see one un-torn session state.
-        const page = paginate(found.agent.session.events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
-        // Views are computed against the registry at pagination time; result
-        // pairing scans within the page only (message-boundary pagination keeps
-        // a call and its result on one page — a cross-page miss soft-falls).
-        const entries: HistoryEntry[] = page.events.map((event) => {
-          const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
-          return { event, ...view === undefined ? {} : { view } }
-        })
+        const page = historyPage(ctx, found.agent.session.events, beforeSeq, maxMessages)
         // Baseline rider: tail page only — loadOlder (beforeSeq present) is
         // the one path that never needs a fresh projection baseline.
         const projections = beforeSeq === undefined ? projectionsFor(ctx, found.agent) : undefined
         return ok(request, {
-          events: entries,
+          events: page.events,
           hasMore: page.hasMore,
           ...projections === undefined ? {} : { projections },
         })
@@ -1592,6 +1691,84 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       },
     },
 
+    subagents: {
+      async list(request, signal) {
+        try {
+          const entries = await ctx.subagents.listChildren(request.payload.parentSessionId, signal)
+          return ok(request, {
+            entries: continuableCatalog(entries),
+            parentAvailable: ctx.agents.get(request.payload.parentSessionId) !== undefined,
+          })
+        } catch (error: unknown) {
+          if (error instanceof SubagentError && error.code === 'CANCELLED') {
+            return err(request, { code: 'cancelled', message: 'subagent catalog read was cancelled', details: {} })
+          }
+          return err(request, { code: 'internal', message: 'subagent catalog read failed', details: {} })
+        }
+      },
+
+      async history(request, signal) {
+        const { parentSessionId, childSessionId, beforeSeq, maxMessages } = request.payload
+        const verified = await healthyCatalogChild(ctx, parentSessionId, childSessionId, signal)
+        if (verified.error !== undefined) return err(request, verified.error)
+        try {
+          const snapshot = await ctx.sessionQuery.readSession(childSessionId)
+          signal?.throwIfAborted()
+          if (snapshot.session.parentSession !== parentSessionId) {
+            return err(request, {
+              code: 'subagent-unauthorized',
+              message: 'subagent parent changed during history read',
+              details: { childSessionId },
+            })
+          }
+          return ok(request, historyPage(ctx, snapshot.events, beforeSeq, maxMessages))
+        } catch (error: unknown) {
+          if (signal?.aborted) {
+            return err(request, { code: 'cancelled', message: 'subagent history read was cancelled', details: {} })
+          }
+          if (error instanceof SessionQueryError) {
+            if (error.code === 'SESSION_QUERY_ABORTED') {
+              return err(request, { code: 'cancelled', message: 'subagent history read was cancelled', details: {} })
+            }
+            if (error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
+              return err(request, {
+                code: 'subagent-not-found',
+                message: 'subagent disappeared during history read',
+                details: { parentSessionId, childSessionId },
+              })
+            }
+          }
+          return err(request, { code: 'internal', message: 'subagent history read failed', details: {} })
+        }
+      },
+
+      async prompt(request, signal) {
+        const { parentSessionId, childSessionId, content } = request.payload
+        const parent = ctx.agents.get(parentSessionId)
+        if (parent === undefined) {
+          return err(request, {
+            code: 'subagent-parent-unavailable',
+            message: `parent session "${parentSessionId}" is not live`,
+            details: { parentSessionId },
+          })
+        }
+        const verified = await healthyCatalogChild(ctx, parentSessionId, childSessionId, signal)
+        if (verified.error !== undefined) return err(request, verified.error)
+        const operationSignal = signal ?? new AbortController().signal
+        try {
+          const messageId = await ctx.subagents.followup(
+            parent,
+            childSessionId,
+            content,
+            { source: { kind: 'user', rpcId: request.rpcId }, signal: operationSignal },
+          )
+          return ok(request, { messageId })
+        } catch (error: unknown) {
+          return subagentPromptError(request, error, operationSignal)
+        }
+      },
+    },
+
     workspace: {
       list(request) {
         return Promise.resolve(ok(request, {

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

@@ -9,6 +9,7 @@ import type { HostApi } from './host.ts'
 import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
 import type { SkillsApi } from './skills.ts'
+import type { SubagentsApi } from './subagents.ts'
 import type { EventsApi } from './events.ts'
 import type { GoalsApi } from './goals.ts'
 import type { SettingsApi } from './settings.ts'
@@ -19,6 +20,7 @@ import type { ClientResponse, RpcReceipt } from './rpc.ts'
 /** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
 export interface ApiProxy {
   sessions: SessionsApi
+  subagents: SubagentsApi
   host: HostApi
   workspace: WorkspaceApi
   commands: CommandsApi
@@ -39,6 +41,9 @@ export type {
   SessionsApi, SessionSummary,
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
+export type {
+  SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, SubagentsApi,
+} from './subagents.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'

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

@@ -13,6 +13,7 @@ import type { GoalsApi } from './goals.ts'
 import type { SettingsApi } from './settings.ts'
 import type { CredentialsApi } from './credentials.ts'
 import type { LlmApi } from './llm.ts'
+import type { SubagentsApi } from './subagents.ts'
 import type { RpcResponse } from './rpc.ts'
 
 /**
@@ -32,6 +33,9 @@ export interface RpcMethodMap {
   'session.prompt': SessionsApi['prompt']
   'session.updateQueue': SessionsApi['updateQueue']
   'session.cancel': SessionsApi['cancel']
+  'subagent.list': SubagentsApi['list']
+  'subagent.history': SubagentsApi['history']
+  'subagent.prompt': SubagentsApi['prompt']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
   'host.listDirectory': HostApi['listDirectory']

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

@@ -56,6 +56,16 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('credential-rejected'), message: z.string(), details: z.object({ ref: z.string() }) }),
   z.object({ code: z.literal('title-invalid'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('fork-unavailable'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-parent-unavailable'), message: z.string(), details: z.object({ parentSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-not-found'), message: z.string(), details: z.object({ parentSessionId: z.string(), childSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-catalog-diagnostic'), message: z.string(), details: z.object({
+    parentSessionId: z.string(),
+    childSessionId: z.string(),
+    reason: z.union([z.literal('corrupt'), z.literal('unsupported'), z.literal('unavailable')]),
+  }) }),
+  z.object({ code: z.literal('subagent-not-resumable'), message: z.string(), details: z.object({ childSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-unauthorized'), message: z.string(), details: z.object({ childSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-not-delivered'), message: z.string(), details: z.object({ childSessionId: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>
 

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

@@ -71,6 +71,16 @@ export interface RpcErrorDetailsMap {
   'credential-rejected': { ref: string }
   'title-invalid': { sessionId: SessionId }
   'fork-unavailable': { sessionId: SessionId }
+  'subagent-parent-unavailable': { parentSessionId: SessionId }
+  'subagent-not-found': { parentSessionId: SessionId; childSessionId: SessionId }
+  'subagent-catalog-diagnostic': {
+    parentSessionId: SessionId
+    childSessionId: SessionId
+    reason: 'corrupt' | 'unsupported' | 'unavailable'
+  }
+  'subagent-not-resumable': { childSessionId: SessionId }
+  'subagent-unauthorized': { childSessionId: SessionId }
+  'subagent-not-delivered': { childSessionId: SessionId }
   'internal': {}
 }
 

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

@@ -194,10 +194,10 @@ export const toolEventViewSchema = z.discriminatedUnion('for', [
 ]) as unknown as z.ZodType<ToolEventView>
 
 /** One session.history item: the session event plus its optional host-computed tool view. */
-export const historyEntrySchema = z.object({
+export const historyEntrySchema: z.ZodType<Wire<HistoryEntry>> = z.object({
   event: sessionEventSchema,
   view: toolEventViewSchema.optional(),
-}) satisfies z.ZodType<Wire<HistoryEntry>>
+}) as unknown as z.ZodType<Wire<HistoryEntry>>
 
 /**
  * Projection baseline passthrough: `values` stays a wide record — each value
@@ -211,11 +211,11 @@ export const sessionProjectionsBlockSchema = z.object({
 }) as unknown as z.ZodType<SessionProjectionsBlock>
 
 /** session.history response value (projections rides the tail page only). */
-export const sessionHistoryValueSchema = z.object({
+export const sessionHistoryValueSchema: z.ZodType<Wire<ResponseValue<'session.history'>>> = z.object({
   events: z.array(historyEntrySchema),
   hasMore: z.boolean(),
   projections: sessionProjectionsBlockSchema.optional(),
-}) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
+})
 
 /** session.models request payload. */
 export const sessionModelsRequestSchema = z.object({

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

@@ -0,0 +1,62 @@
+/** Zod schemas for the browser-safe subagent domain. */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import { contentBlockSchema, historyEntrySchema, sessionIdSchema } from './sessions.schema.ts'
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+import type { SubagentListEntry } from './subagents.ts'
+
+/** Healthy and diagnostic durable catalog rows. */
+export const subagentListEntrySchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('child'),
+    id: sessionIdSchema,
+    label: z.string(),
+    activity: z.union([z.literal('running'), z.literal('inactive')]),
+  }),
+  z.object({
+    kind: z.literal('diagnostic'),
+    id: sessionIdSchema,
+    reason: z.union([z.literal('corrupt'), z.literal('unsupported'), z.literal('unavailable')]),
+  }),
+]) satisfies z.ZodType<Wire<SubagentListEntry>>
+
+/** subagent.list request payload. */
+export const subagentListRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.list'>>>
+
+/** subagent.list response value. */
+export const subagentListValueSchema = z.object({
+  entries: z.array(subagentListEntrySchema),
+  parentAvailable: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.list'>>>
+
+/** subagent.history request payload. */
+export const subagentHistoryRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  beforeSeq: z.number().int().nonnegative().optional(),
+  maxMessages: z.number().int().positive().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.history'>>>
+
+/** subagent.history response value. */
+export const subagentHistoryValueSchema = z.object({
+  events: z.array(historyEntrySchema),
+  hasMore: z.boolean(),
+}) as unknown as z.ZodType<Wire<ResponseValue<'subagent.history'>>>
+
+/** subagent.prompt request payload. */
+export const subagentPromptRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  content: z.array(contentBlockSchema),
+}) as unknown as z.ZodType<RequestPayload<'subagent.prompt'>>
+
+const messageIdSchema = z.string() as unknown as z.ZodType<MessageId>
+
+/** subagent.prompt response value. */
+export const subagentPromptValueSchema = z.object({
+  messageId: messageIdSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.prompt'>>>

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

@@ -0,0 +1,72 @@
+/**
+ * Browser-safe subagent domain contract. Persisted transcript reads never
+ * activate an Agent, while prompts route through the direct parent's
+ * Activation-backed continuation owner.
+ */
+
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+import type { HistoryEntry } from './sessions.ts'
+
+/** Complete durable direct-child catalog row. */
+export type SubagentListEntry =
+  | {
+    kind: 'child'
+    id: SessionId
+    label: string
+    activity: 'running' | 'inactive'
+  }
+  | {
+    kind: 'diagnostic'
+    id: SessionId
+    reason: 'corrupt' | 'unsupported' | 'unavailable'
+  }
+
+/** Inbox identity returned once the continuation accepts one human message. */
+export interface SubagentPromptReceipt {
+  messageId: MessageId
+}
+
+/** Durable parent/child address that selects subagent transport in the client. */
+export interface SubagentAddress {
+  parentSessionId: SessionId
+  childSessionId: SessionId
+}
+
+/** Complete direct-child catalog plus the delivery-time parent availability hint. */
+export interface SubagentCatalog {
+  entries: SubagentListEntry[]
+  parentAvailable: boolean
+}
+
+/** Subagent-domain unary methods. */
+export interface SubagentsApi {
+  /**
+   * Lists direct continuable children without loading either side. Parent
+   * availability is a hint; prompt performs the authoritative check.
+   */
+  list(
+    request: RpcRequest<{ parentSessionId: SessionId }>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<SubagentCatalog>>
+
+  /**
+   * Reads one healthy catalog child's persisted raw log with ordinary
+   * message-aligned pagination and render intents, without Agent activation.
+   */
+  history(
+    request: RpcRequest<SubagentAddress & { beforeSeq?: number; maxMessages?: number }>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>>
+
+  /**
+   * Delivers human content through the exact live parent's continuation
+   * owner. Success identifies the accepted inbox message.
+   */
+  prompt(
+    request: RpcRequest<SubagentAddress & { content: ContentBlock[] }>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<SubagentPromptReceipt>>
+}

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

@@ -55,6 +55,11 @@ import {
   credentialsDescribeValueSchema, credentialsSetValueSchema, credentialsUnsetValueSchema,
 } from '../api/credentials.schema.ts'
 import { llmModelsValueSchema, llmProvidersValueSchema } from '../api/llm.schema.ts'
+import {
+  subagentHistoryValueSchema,
+  subagentListValueSchema,
+  subagentPromptValueSchema,
+} from '../api/subagents.schema.ts'
 
 /**
  * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
@@ -86,6 +91,11 @@ export interface IApiClient {
     updateQueue(payload: RequestPayload<'session.updateQueue'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.updateQueue'>>>
     cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
   }
+  subagents: {
+    list(payload: RequestPayload<'subagent.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.list'>>>
+    history(payload: RequestPayload<'subagent.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.history'>>>
+    prompt(payload: RequestPayload<'subagent.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.prompt'>>>
+  }
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
     pickDirectory(payload: RequestPayload<'host.pickDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.pickDirectory'>>>
@@ -155,6 +165,9 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.prompt': sessionPromptValueSchema,
   'session.updateQueue': sessionUpdateQueueValueSchema,
   'session.cancel': sessionCancelValueSchema,
+  'subagent.list': subagentListValueSchema,
+  'subagent.history': subagentHistoryValueSchema,
+  'subagent.prompt': subagentPromptValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
   'host.listDirectory': hostListDirectoryValueSchema,
@@ -385,6 +398,12 @@ export abstract class AbstractApiClient implements IApiClient {
     cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
   }
 
+  readonly subagents: IApiClient['subagents'] = {
+    list: (payload, signal) => this.callUnary('subagent.list', payload, signal),
+    history: (payload, signal) => this.callUnary('subagent.history', payload, signal),
+    prompt: (payload, signal) => this.callUnary('subagent.prompt', payload, signal),
+  }
+
   readonly host: IApiClient['host'] = {
     describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
     // A native system dialog is user-paced and may legitimately stay open

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

@@ -57,6 +57,11 @@ import {
   credentialsDescribeRequestSchema, credentialsSetRequestSchema, credentialsUnsetRequestSchema,
 } from '../api/credentials.schema.ts'
 import { llmModelsRequestSchema, llmProvidersRequestSchema } from '../api/llm.schema.ts'
+import {
+  subagentHistoryRequestSchema,
+  subagentListRequestSchema,
+  subagentPromptRequestSchema,
+} from '../api/subagents.schema.ts'
 
 /**
  * Unary dispatch table, keyed by (and compiler-locked to) RpcMethodMap: a map row without a
@@ -87,6 +92,9 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
   'session.updateQueue': { schema: sessionUpdateQueueRequestSchema, invoke: (api, r) => api.sessions.updateQueue(r) },
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
+  'subagent.list': { schema: subagentListRequestSchema, invoke: (api, r, signal) => api.subagents.list(r, signal) },
+  'subagent.history': { schema: subagentHistoryRequestSchema, invoke: (api, r, signal) => api.subagents.history(r, signal) },
+  'subagent.prompt': { schema: subagentPromptRequestSchema, invoke: (api, r, signal) => api.subagents.prompt(r, signal) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
   'host.listDirectory': { schema: hostListDirectoryRequestSchema, invoke: (api, r, signal) => api.host.listDirectory(r, signal) },

packages/host/apiproxy/src/index.ts

@@ -45,7 +45,10 @@ export interface Config {
  * project directory and the fallback parent for name-created Workspaces.
  */
 export class ApiProxyService extends Service implements ApiProxy {
-  static inject = ['agents', 'directoryPicker', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
+  static inject = [
+    'agents', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
+    'tools', 'userInteraction', 'workspace',
+  ]
 
   static Config: z<Config> = z.object({
     provider: z.string().required(),
@@ -54,6 +57,7 @@ export class ApiProxyService extends Service implements ApiProxy {
   })
 
   readonly sessions: ApiProxy['sessions']
+  readonly subagents: ApiProxy['subagents']
   readonly workspace: ApiProxy['workspace']
   readonly host: ApiProxy['host']
   readonly commands: ApiProxy['commands']
@@ -75,6 +79,7 @@ export class ApiProxyService extends Service implements ApiProxy {
       workspaceRoot: resolve(config.workspaceRoot ?? cwd),
     })
     this.sessions = api.sessions
+    this.subagents = api.subagents
     this.workspace = api.workspace
     this.host = api.host
     this.commands = api.commands

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

@@ -0,0 +1,169 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { SessionQueryError } from '@deepseek-ai/dsh-session-query'
+import { SubagentError } from '@deepseek-ai/dsh-subagent'
+import { RpcId } from '../src/api/rpc.ts'
+import type { RpcRequest } from '../src/api/rpc.ts'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const sid = (value: string): SessionId => value as SessionId
+const PARENT = sid('parent')
+const CHILD = sid('child')
+
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId('subagent-rpc'), payload }
+}
+
+function bench(options: {
+  parentLive?: boolean
+  entries?: object[]
+  followupError?: Error
+  listError?: Error
+  readError?: Error
+  historyParent?: SessionId
+} = {}) {
+  const parent = { id: PARENT }
+  const getAgent = vi.fn((id: SessionId) =>
+    options.parentLive !== false && id === PARENT ? parent : undefined)
+  const listChildren = vi.fn(() => options.listError === undefined
+    ? Promise.resolve(options.entries ?? [
+      { kind: 'child', id: CHILD, mode: 'continuable', label: 'worker', activity: 'inactive' },
+    ])
+    : Promise.reject(options.listError))
+  const followup = vi.fn((
+    _parent: unknown,
+    _childId: SessionId,
+    _content: unknown,
+    _delivery: { source: { kind: string; rpcId: RpcId }; signal: AbortSignal },
+  ) => options.followupError === undefined
+    ? Promise.resolve('message-1')
+    : Promise.reject(options.followupError))
+  const readSession = vi.fn(() => options.readError === undefined
+    ? Promise.resolve({
+      session: {
+        version: 0, id: CHILD, createdAt: 1, parentSession: options.historyParent ?? PARENT,
+      } satisfies SessionHeader,
+      events: [
+        { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } } },
+      ] as unknown as SessionEvent[],
+    })
+    : Promise.reject(options.readError))
+  const ctx = new Context()
+  ctx.provide('agents', { get: getAgent })
+  ctx.provide('subagents', { listChildren, followup })
+  ctx.provide('sessionQuery', { readSession })
+  ctx.provide('userInteraction', { registerProvider: () => () => {} })
+  const api = createApiProxy(ctx, {
+    provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp',
+  })
+  return { api, getAgent, listChildren, readSession, followup, parent }
+}
+
+describe('subagent gateway', () => {
+  it('lists the complete catalog and reports exact live-parent availability', async () => {
+    const { api, listChildren } = bench({ parentLive: false, entries: [
+      { kind: 'child', id: CHILD, mode: 'continuable', label: 'worker', activity: 'inactive' },
+      { kind: 'child', id: sid('one-shot'), mode: 'one-shot', activity: 'inactive' },
+      { kind: 'diagnostic', id: sid('bad'), reason: 'corrupt' },
+    ] })
+    const response = await api.subagents.list(request({ parentSessionId: PARENT }))
+    expect(response.rpcId).toBe('subagent-rpc')
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { parentAvailable: false, entries: [{ kind: 'child' }, { kind: 'diagnostic' }] },
+    })
+    expect(listChildren).toHaveBeenCalledWith(PARENT, undefined)
+  })
+
+  it('reads a healthy direct child without looking up or activating any Agent', async () => {
+    const { api, getAgent, readSession } = bench()
+    const response = await api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD, maxMessages: 10,
+    }))
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { hasMore: false, events: [{ event: { type: 'user/message', seq: 0 } }] },
+    })
+    expect(readSession).toHaveBeenCalledWith(CHILD)
+    expect(getAgent).not.toHaveBeenCalled()
+  })
+
+  it('rejects a diagnostic address before reading history', async () => {
+    const { api, readSession } = bench({ entries: [
+      { kind: 'diagnostic', id: CHILD, reason: 'unsupported' },
+    ] })
+    const response = await api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD,
+    }))
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'subagent-catalog-diagnostic',
+        details: { parentSessionId: PARENT, childSessionId: CHILD, reason: 'unsupported' },
+      },
+    })
+    expect(readSession).not.toHaveBeenCalled()
+  })
+
+  it('routes human content through the exact live parent with rpc attribution', async () => {
+    const { api, parent, followup } = bench()
+    const content = [{ type: 'text' as const, text: '继续' }]
+    const response = await api.subagents.prompt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, content,
+    }))
+    expect(response.result).toMatchObject({
+      ok: true, value: { messageId: 'message-1' },
+    })
+    expect(followup).toHaveBeenCalledTimes(1)
+    const [actualParent, actualChild, actualContent, delivery] = followup.mock.calls[0]!
+    expect([actualParent, actualChild, actualContent]).toEqual([parent, CHILD, content])
+    expect(delivery.source).toEqual({ kind: 'user', rpcId: RpcId('subagent-rpc') })
+    expect(delivery.signal).toBeInstanceOf(AbortSignal)
+  })
+
+  it('fails before delivery when the parent is absent and maps continuation failures', async () => {
+    const absent = bench({ parentLive: false })
+    expect((await absent.api.subagents.prompt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, content: [],
+    }))).result).toMatchObject({ ok: false, error: { code: 'subagent-parent-unavailable' } })
+    expect(absent.listChildren).not.toHaveBeenCalled()
+
+    const failed = bench({ followupError: new SubagentError('not delivered', 'DRAINING') })
+    expect((await failed.api.subagents.prompt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, content: [],
+    }))).result).toMatchObject({ ok: false, error: { code: 'subagent-not-delivered' } })
+  })
+
+  it('maps history disappearance and hides unexpected backend details', async () => {
+    const disappeared = bench({
+      readError: new SessionQueryError('secret path', 'SESSION_QUERY_SESSION_NOT_FOUND'),
+    })
+    expect((await disappeared.api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD,
+    }))).result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'subagent-not-found',
+        message: 'subagent disappeared during history read',
+        details: { parentSessionId: PARENT, childSessionId: CHILD },
+      },
+    })
+
+    const catalog = bench({ listError: new Error('secret descriptor') })
+    expect((await catalog.api.subagents.list(request({
+      parentSessionId: PARENT,
+    }))).result).toMatchObject({
+      ok: false,
+      error: { code: 'internal', message: 'subagent catalog read failed' },
+    })
+
+    const prompt = bench({ followupError: new Error('secret provider') })
+    expect((await prompt.api.subagents.prompt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, content: [],
+    }))).result).toMatchObject({
+      ok: false,
+      error: { code: 'internal', message: 'subagent prompt failed' },
+    })
+  })
+})

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

@@ -19,6 +19,7 @@ function ok<T>(request: RpcRequest<unknown>, value: T): Promise<RpcResponse<T>>
 /** Scripted impl: every method resolves an empty-ish OK unless a case overrides it. */
 function scriptedApi(overrides: {
   sessions?: Partial<ApiProxy['sessions']>
+  subagents?: Partial<ApiProxy['subagents']>
   host?: Partial<ApiProxy['host']>
   commands?: Partial<ApiProxy['commands']>
   skills?: Partial<ApiProxy['skills']>
@@ -57,6 +58,12 @@ function scriptedApi(overrides: {
       cancel: r => ok(r, { accepted: true as const }),
       ...overrides.sessions,
     },
+    subagents: {
+      list: r => ok(r, { entries: [], parentAvailable: false }),
+      history: r => ok(r, { events: [], hasMore: false }),
+      prompt: r => ok(r, { messageId: 'message-1' as never }),
+      ...overrides.subagents,
+    },
     host: {
       describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }),
       pickDirectory: r => ok(r, { path: null }),

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

@@ -103,6 +103,20 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
     },
+    subagents: {
+      async list(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { entries: [], parentAvailable: false } } }
+      },
+      async history(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { events: [], hasMore: false } } }
+      },
+      async prompt(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { messageId: 'message-1' as never } },
+        }
+      },
+    },
     host: {
       async describe(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0 } } }

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

@@ -36,6 +36,11 @@ import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../s
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
 import { goalEditRequestSchema } from '../src/api/goals.schema.ts'
+import {
+  subagentHistoryRequestSchema, subagentHistoryValueSchema, subagentListEntrySchema,
+  subagentListRequestSchema, subagentListValueSchema, subagentPromptRequestSchema,
+  subagentPromptValueSchema,
+} from '../src/api/subagents.schema.ts'
 
 describe('RpcId', () => {
   it('brands a raw string at zero runtime cost', () => {
@@ -75,6 +80,12 @@ describe('rpcErrorSchema', () => {
     expect(rpcErrorSchema.parse({ code: 'command-error', message: 'm', details: {} }).code).toBe('command-error')
     expect(rpcErrorSchema.parse({ code: 'unknown-command', message: 'm', details: {} }).code).toBe('unknown-command')
     expect(rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: { sessionId: 's' } }).code).toBe('title-invalid')
+    expect(rpcErrorSchema.parse({ code: 'subagent-parent-unavailable', message: 'm', details: { parentSessionId: 'p' } }).code).toBe('subagent-parent-unavailable')
+    expect(rpcErrorSchema.parse({ code: 'subagent-not-found', message: 'm', details: { parentSessionId: 'p', childSessionId: 'c' } }).code).toBe('subagent-not-found')
+    expect(rpcErrorSchema.parse({ code: 'subagent-catalog-diagnostic', message: 'm', details: { parentSessionId: 'p', childSessionId: 'c', reason: 'corrupt' } }).code).toBe('subagent-catalog-diagnostic')
+    expect(rpcErrorSchema.parse({ code: 'subagent-not-resumable', message: 'm', details: { childSessionId: 'c' } }).code).toBe('subagent-not-resumable')
+    expect(rpcErrorSchema.parse({ code: 'subagent-unauthorized', message: 'm', details: { childSessionId: 'c' } }).code).toBe('subagent-unauthorized')
+    expect(rpcErrorSchema.parse({ code: 'subagent-not-delivered', message: 'm', details: { childSessionId: 'c' } }).code).toBe('subagent-not-delivered')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
   })
 
@@ -272,6 +283,34 @@ describe('sessions domain schemas', () => {
   })
 })
 
+describe('subagent domain schemas', () => {
+  it('validates the direct catalog and addressed history pair', () => {
+    const child = { kind: 'child', id: 'c', label: 'worker', activity: 'running' }
+    const diagnostic = { kind: 'diagnostic', id: 'bad', reason: 'unsupported' }
+    expect(subagentListEntrySchema.parse(child)).toEqual(child)
+    expect(subagentListEntrySchema.parse(diagnostic)).toEqual(diagnostic)
+    expect(subagentListRequestSchema.parse({ parentSessionId: 'p' })).toEqual({ parentSessionId: 'p' })
+    expect(subagentListValueSchema.parse({
+      entries: [child, diagnostic], parentAvailable: true,
+    }).entries).toHaveLength(2)
+    expect(subagentHistoryRequestSchema.parse({
+      parentSessionId: 'p', childSessionId: 'c', beforeSeq: 4, maxMessages: 2,
+    }).beforeSeq).toBe(4)
+    expect(() => subagentHistoryRequestSchema.parse({
+      parentSessionId: 'p', childSessionId: 'c', maxMessages: 0,
+    })).toThrow()
+    expect(subagentHistoryValueSchema.parse({ events: [], hasMore: false }).hasMore).toBe(false)
+  })
+
+  it('validates prompt content and the accepted inbox identity', () => {
+    expect(subagentPromptRequestSchema.parse({
+      parentSessionId: 'p', childSessionId: 'c', content: [{ type: 'text', text: '继续' }],
+    }).childSessionId).toBe('c')
+    expect(subagentPromptValueSchema.parse({ messageId: 'm1' }).messageId).toBe('m1')
+    expect(() => subagentPromptValueSchema.parse({ taskId: 't1' })).toThrow()
+  })
+})
+
 describe('host domain schemas', () => {
   it('validates describe request/value', () => {
     expect(hostDescribeRequestSchema.parse({})).toEqual({})

packages/host/apiproxy/tsconfig.json

@@ -53,6 +53,12 @@
     {
       "path": "../../session-title/session-title"
     },
+    {
+      "path": "../../session-query/session-query"
+    },
+    {
+      "path": "../../subagent/subagent"
+    },
     {
       "path": "../../skill/skill"
     },