feat: optimize subagent list children query

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: 45e79aea55665882faeee14201a2c2dda6fe9199
-README.zh.md: cb0cbe4fe53a3d328adbb57671ce6aa4a439470c
+README.md: 5755850e77dbd247b8808d907d813aecf2a650aa
+README.zh.md: 02048fdbf2eaca3458b34d508731dfc9df1e90d3

packages/host/apiproxy/README.md

@@ -38,7 +38,7 @@ 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).
+The `subagent.*` domain addresses direct children by `{parentSessionId, childSessionId}`. `subagent.list` projects the complete durable one-shot and continuable catalog from `ctx.subagents.listChildren`, including each healthy row's origin-classified `hasChildren` hint plus an exact-live-parent hint; `subagent.history` verifies a healthy direct-child entry and reads its persisted log through `ctx.sessionQuery` without resuming an Agent. `subagent.prompt` accepts only continuable addresses, 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)
 

packages/host/apiproxy/README.zh.md

@@ -38,7 +38,7 @@ 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)。
+`subagent.*` 领域通过 `{parentSessionId, childSessionId}` 寻址直接 child。`subagent.list` 从 `ctx.subagents.listChildren` 投影包含 one-shot 与可继续条目的完整持久化目录、每个健康行基于 origin 分类的 `hasChildren` 提示，以及确切 parent 是否存活的提示；`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` + 根路径）
 

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

@@ -16,6 +16,7 @@ export const subagentListEntrySchema = z.union([
     id: sessionIdSchema,
     mode: z.literal('one-shot'),
     activity: z.union([z.literal('running'), z.literal('inactive')]),
+    hasChildren: z.boolean(),
     label: z.string().optional(),
   }),
   z.object({
@@ -23,6 +24,7 @@ export const subagentListEntrySchema = z.union([
     id: sessionIdSchema,
     mode: z.literal('continuable'),
     activity: z.union([z.literal('running'), z.literal('inactive')]),
+    hasChildren: z.boolean(),
     label: z.string(),
   }),
   z.object({

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

@@ -16,6 +16,8 @@ export type SubagentListEntry =
     kind: 'child'
     id: SessionId
     activity: 'running' | 'inactive'
+    /** Whether a direct descendant has durable `origin: 'subagent'`. */
+    hasChildren: boolean
   } & (
     | {
       mode: 'one-shot'

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

@@ -28,7 +28,10 @@ function bench(options: {
     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' },
+      {
+        kind: 'child', id: CHILD, mode: 'continuable', label: 'worker',
+        activity: 'inactive', hasChildren: false,
+      },
     ])
     : Promise.reject(options.listError))
   const followup = vi.fn((
@@ -63,8 +66,14 @@ function bench(options: {
 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: 'child', id: CHILD, mode: 'continuable', label: 'worker',
+        activity: 'inactive', hasChildren: true,
+      },
+      {
+        kind: 'child', id: sid('one-shot'), mode: 'one-shot',
+        activity: 'inactive', hasChildren: false,
+      },
       { kind: 'diagnostic', id: sid('bad'), reason: 'corrupt' },
     ] })
     const response = await api.subagents.list(request({ parentSessionId: PARENT }))
@@ -98,7 +107,8 @@ describe('subagent gateway', () => {
 
   it('reads one-shot history and rejects an address with the wrong mode', async () => {
     const oneShot = {
-      kind: 'child', id: CHILD, mode: 'one-shot', label: 'batch', activity: 'inactive',
+      kind: 'child', id: CHILD, mode: 'one-shot', label: 'batch',
+      activity: 'inactive', hasChildren: false,
     }
     const { api, readSession } = bench({ entries: [oneShot] })
     expect((await api.subagents.history(request({

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

@@ -292,13 +292,19 @@ describe('sessions domain schemas', () => {
 describe('subagent domain schemas', () => {
   it('validates the direct catalog and addressed history pair', () => {
     const child = {
-      kind: 'child', id: 'c', mode: 'continuable', label: 'worker', activity: 'running',
+      kind: 'child', id: 'c', mode: 'continuable', label: 'worker',
+      activity: 'running', hasChildren: true,
+    }
+    const oneShot = {
+      kind: 'child', id: 'o', mode: 'one-shot', activity: 'inactive', hasChildren: false,
     }
-    const oneShot = { kind: 'child', id: 'o', mode: 'one-shot', activity: 'inactive' }
     const diagnostic = { kind: 'diagnostic', id: 'bad', reason: 'unsupported' }
     expect(subagentListEntrySchema.parse(child)).toEqual(child)
     expect(subagentListEntrySchema.parse(oneShot)).toEqual(oneShot)
     expect(subagentListEntrySchema.parse(diagnostic)).toEqual(diagnostic)
+    expect(() => subagentListEntrySchema.parse({
+      kind: 'child', id: 'missing', mode: 'one-shot', activity: 'inactive',
+    })).toThrow()
     expect(subagentListRequestSchema.parse({ parentSessionId: 'p' })).toEqual({ parentSessionId: 'p' })
     expect(subagentListValueSchema.parse({
       entries: [child, oneShot, diagnostic], parentAvailable: true,