Shared continuable Activation capacity
共享的可续接 Activation 容量
Depth limits bound nesting but permit wide concurrent delegation. Background Job limits do not cover continuable children, and a lifetime creation quota prevents useful later work after earlier children finish.
English
Problem
Depth limits bound nesting but permit wide concurrent delegation. Background Job limits do not cover continuable children, and a lifetime creation quota prevents useful later work after earlier children finish.
Decision
The subagent service configures maxActiveSubagents, defaulting to 8. Each live non-continuable parent owns one process-local pool, shared by reference through uninterrupted continuable parent links. The pool owner itself is excluded. One-shot runs and external-provider work do not enter this pool. A one-shot intermediate parent starts a separate pool for its continuable children; cross-one-shot capacity inheritance is deferred. Delegation depth remains independently configured.
The Activation registry reserves a unique slot before fresh or cold-resume reconstruction yields. The materialization owns rollback until the Activation owns the slot; unpublished rollback and failed materialization may both release the same token safely. Handle disposal precedes release, which precedes parent settlement notification. Sending to an existing Activation reuses its slot.
Pool lookup, admission and release take amortized constant time. A weak root map does not retain dead root Agents; each pool holds only occupied tokens. No Session catalog scan, tree traversal, durable counter, or public capacity-query API is added.
The Host registers the subagent settings section over its composition. Each reservation reads the current capacity, so lowering it never evicts resident children or rebuilds their registry. Delegation tools resolve an omitted depth from the same section at each attempt; explicit numeric and provider-managed tool policies retain priority. The GUI stages both numbers and resets each to composition through the existing revision-fenced settings path. Keeping counts in the pool and policy in settings avoids a second live counter or a settings-triggered teardown.
Alternatives considered
A cumulative child count is a separate cost policy and does not release capacity after useful work finishes. Counting model requests would omit waiting parents, queued inbox work, reconstruction and cleanup, all of which retain resources. Scanning resident and pending maps adds work proportional to unrelated live trees. Separate counters require synchronization with slot ownership.
Waiting for capacity can deadlock when every slot belongs to a parent waiting for a descendant. Full pools reject with an actionable diagnostic instead of retaining queued activation requests.
Consequences
Idle Activations with pending inbox work or owned descendants still occupy slots. Cold resume can fail at capacity even though the historical child exists; browser prompts report this as subagent/delivery-unavailable. Slots do not impose a token or cumulative spending budget, and they do not coordinate multiple harness processes.
The continuable lifecycle decision retains ownership of settlement and child-first teardown. This capacity policy extends that lifecycle without changing durable Session data.
Verification
Focused continuation tests exercise the default, invalid configuration, shared multi-level capacity, root isolation, pending creation, failure release, cold resume, resident messages and disposal. A keyless SDK-profile snapshot records successful background creation followed by an over-capacity tool diagnostic while the first child remains live.
中文
Problem
深度限制约束嵌套层数，但仍允许大量并发委派。后台 Job 限制不覆盖可续接子代理，而生命周期累计创建配额会在早期子代理完成后阻止有用的后续工作。
Decision
Subagent 服务通过 maxActiveSubagents 配置容量，默认值为 8。每个存活的非可续接父代理拥有一个进程内池，通过连续的可续接父子关系按引用共享。池的所有者自身不计入。一次性运行和外部提供方工作不进入此池。一次性中间父代理为其可续接子代理建立独立的池；跨一次性代理的容量池继承暂不实现。委派深度仍独立配置。
Activation registry 在新建或冷恢复重建首次让出执行前预占唯一名额。在 Activation 接管名额前，由 materialization 负责回滚；未发布回滚和失败的 materialization 可以安全地释放同一个 token。handle 释放先于名额归还，名额归还先于父代理完成通知。向已有 Activation 发送消息复用其名额。
池查找、接纳和释放的摊还时间复杂度均为常数。根代理的弱引用映射不会保留已结束的根 Agent；每个池只持有已占用的 token。不增加 Session 目录扫描、树遍历、持久计数器或公开的容量查询 API。
Host 在组合配置之上注册 subagent 设置分节。每次预占读取当前容量，因此调低上限不会驱逐驻留子代理，也不会重建注册表。委派工具在每次尝试时从同一分节解析省略的深度；显式数值和 provider-managed 工具策略保留优先级。GUI 暂存两个数值，并通过现有的 revision 校验设置路径分别恢复组合默认值。池持有计数、设置持有策略，避免增加第二份在线计数或因设置变更而触发拆除。
Alternatives considered
累计子代理计数是另一种成本策略，不会在有用工作完成后释放容量。只统计模型请求会遗漏等待后代的父代理、收件箱排队内容、重建和清理，这些阶段都占用资源。扫描驻留和待创建映射会增加与无关存活任务树数量成正比的工作。独立计数器需要与名额所有权同步。
当所有名额都属于等待后代的父代理时，等待容量可能造成死锁。池满时返回可操作诊断，不保留排队的激活请求。
Consequences
有待处理收件箱内容或所拥有后代的空闲 Activation 仍占名额。容量耗尽时，即使历史子代理存在，冷恢复也可能失败；浏览器消息将其报告为 subagent/delivery-unavailable。名额不构成 token 或累计费用预算，也不协调多个 Harness 进程。
可续接生命周期决策 仍负责完成判定和先子后父的清理。本容量策略扩展该生命周期，不修改持久 Session 数据。
Verification
聚焦的续接测试覆盖默认值、非法配置、多层共享容量、根代理隔离、待完成创建、失败归还、冷恢复、驻留消息和释放。免密 SDK profile 快照记录后台创建成功，以及首个子代理仍存活时再次创建所产生的超限工具诊断。