knowledge-capacity-lifecycle-and-egress

name

knowledge-capacity-lifecycle-and-egress

description

覆盖 Session、Task、Tool、Provider、Browser 的有界准入，跨 Session 公平性，SSE/ACP/Headless 输出背压，以及取消、关闭和进程树回收。 使用时机：排查 429/resource_exhausted、队列饥饿、内存增长、输出乱序、Session 驱逐、Browser 容量、关闭挂起或孤儿进程。 不包含：Provider 重试/熔断算法见 model-and-provider-runtime/provider-resilience-admission-and-observability，Shell 业务工具见 tool-and-automation-platform/shell-process-and-worktree。 关键词：SessionRuntimeResidency, TaskRunScheduler, ConcurrencyScheduler, ProviderRequestAdmissionScheduler, BrowserProcessPool, BoundedSerialEgress, GracefulShutdown。

Module Structure

该横切域用不同粒度的 reservation、permit、lease 和串行 egress 控制有限资源；每层都拥有独立队列、失败类型和释放责任，不能用一个全局 semaphore 替代。

Directory Layout

• packages/cli/src/agent/runtime/SessionRuntimeResidency.ts — Web/ACP Runtime 驻留、pin、LRU 和 reservation
• packages/cli/src/agent/runtime/TaskRunScheduler.ts — 顶层 Task active/pending count 与 retained bytes
• packages/cli/src/tools/execution/ConcurrencyScheduler.ts — 进程和 Session 两级工具公平准入
• packages/cli/src/tools/execution/ToolConcurrencyGate.ts — 单 executor 的 shared/exclusive FIFO 屏障
• packages/cli/src/services/pi/providerRequestAdmission.ts — Provider domain/owner/class 加权准入
• packages/cli/src/browser/BrowserOperationGate.ts — 单 Session Browser 操作串行化
• packages/cli/src/browser/BrowserProcessPool.ts — 共享 Chromium 与隔离 Context lease
• packages/cli/src/utils/BoundedSerialEgress.ts — 通用有界单写者输出
• packages/cli/src/server/OrderedSseEgress.ts — replay/live 交接和 committed seq 顺序
• packages/cli/src/services/GracefulShutdown.ts — 信号、清理栈、Hook 和日志关闭
• packages/cli/src/utils/process/ — owned process tree、admission gate 和 PID identity

Decision Entry

• SessionRuntimeResidency.reserve() — 初始化前预留 Runtime 容量
• TaskRunScheduler.admit() — 顶层任务立即运行或进入 FIFO 队列
• ConcurrencyScheduler.schedule() — 按 Session round-robin 获取工具 permit
• ProviderRequestAdmissionScheduler.admit() — 按 failure domain、root owner 和 request class 准入
• BrowserOperationGate.run() / BrowserProcessPool.acquire() — 页面操作与 Chromium Context 两级容量
• BoundedSerialEgress.offer() — 在保留输出前同步判定 item/byte 上限
• GracefulShutdownManager.shutdown() — 取消活动命令并有界执行清理

Branching Table

资源	有容量时	等待或可回收时	满载、失败或关闭时
Session Runtime	reservation 计数后初始化并 commit lease	Web 可驱逐 idle、unpinned、canEvict 的 LRU resident	ACP 不驱逐；无候选返回可重试 resident_runtimes
顶层 Task	active slot 空闲则立即运行且不计 pending bytes	paused 或 active 满时按 FIFO 计 pending count/bytes	任一 pending 上限命中即在执行前拒绝
工具进程级准入	同时满足 global/session total 与 kind 限额后执行	每个 Session 只取队首，跨 Session round-robin	queue full 或 180 秒等待超时返回 tool_busy
工具批内 gate	连续 shared 调用并发	exclusive 调用作为 FIFO 屏障	pending 超 64 或 close 时取消未启动调用
Provider stream	未配置并发旋钮时直接请求；配置后取得 physical-attempt permit	foreground 优先、owner round-robin，background/internal 可 aging	count/bytes/full/timeout 返回脱敏可重试错误
Browser	进程池复用一个 Chromium，每 Session 独立 Context，操作严格 FIFO	最后一个 Context release 时关闭 Chromium	Context 或操作队列满分别返回 browser_capacity / browser_busy
Surface egress	单 writer 按接纳顺序输出	flush() 只等待调用时已接纳的 high-water mark	overflow、oversized、write failure/timeout 关闭整条通道
进程关闭	cleanup handlers 按注册逆序等待	单项失败继续执行其余 cleanup	4 秒 cleanup budget 后报错，5 秒 hard timeout 强制退出

Affected Scope

• packages/cli/src/server/routes/session.ts — Web Runtime 驻留、Task 429 映射和 Session SSE
• packages/cli/src/acp/BladeAgent.ts 与 packages/cli/src/acp/Session.ts — ACP 不驱逐驻留和有界 update egress
• packages/cli/src/commands/headless.ts 与 packages/cli/src/commands/HeadlessOutputEgress.ts — Headless 信号传播和 stdout/stderr 背压
• packages/cli/src/tools/execution/ToolExecutor.ts — 工具批内 gate、进程 permit 和 owner dispose
• packages/cli/src/services/PiAIChatService.ts — 每次 physical Provider attempt 的准入与释放
• packages/cli/src/browser/SessionBrowserRuntime.ts — Session 页面操作、Context lease 和 dispose
• packages/cli/src/context/storage/ — 前台命令 lease、孤儿恢复和 durable process sidecar
• packages/cli/src/hooks/SecureProcessExecutor.ts 与 packages/cli/src/lsp/LspClient.ts — 共用 owned process tree
• packages/cli/web/src/store/session/ — 容量事件、队列位置和流状态投影

Gotchas

• Session Runtime 的未完成 reservation 也占硬上限，避免并发初始化在 commit 前穿透容量；所有创建失败路径都必须调用 cancel() (packages/cli/src/agent/runtime/SessionRuntimeResidency.ts)
• Web 只能驱逐 idle、未 pin、canEvict() 为真的 Runtime；ACP resident 永不隐式驱逐，客户端必须显式 session/close (packages/cli/src/agent/runtime/SessionRuntimeResidency.ts, docs/configuration/config-system.md)
• 被驱逐 Runtime 的 dispose() 失败时会恢复为 poisoned resident；它仍占容量但不可 acquire 或再次驱逐，防止把未确认清理的资源当作空位 (packages/cli/src/agent/runtime/SessionRuntimeResidency.ts)
• Task 和 Provider 的 byte budget 只约束等待队列；单个超过 pending budget 的请求在 active slot 空闲时仍可立即运行，但一旦需要排队就会被拒绝 (packages/cli/src/agent/runtime/TaskRunScheduler.ts, packages/cli/src/services/pi/providerRequestAdmission.ts)
• TaskRunScheduler.configure() 冻结进程级限制，单个 Session 的 admission options 不能把它降成项目私有值；project 配置不得覆盖进程容量 (packages/cli/src/agent/runtime/TaskRunScheduler.ts)
• 工具有两层独立顺序：ToolConcurrencyGate 保证同批 shared/exclusive 屏障，ConcurrencyScheduler 再限制进程/Session total 与 kind；删除任一层都会改变读写顺序或跨 Session 公平性 (packages/cli/src/tools/execution/ToolConcurrencyGate.ts, packages/cli/src/tools/execution/ConcurrencyScheduler.ts)
• 工具 validation、worktree 隔离、Hook、权限和人工审批发生在 scarce permit 前；把审批移到 scheduler 内会让等待用户的调用长期占用执行容量 (packages/cli/src/tools/execution/ToolExecutor.ts, docs/reference/tool-concurrency.md)
• Provider admission 默认关闭，只有配置 domain/global/owner 任一并发旋钮才启用；不能把 scheduler 常量误当成未配置时的隐藏吞吐限制 (packages/cli/src/services/PiAIChatService.ts, docs/reference/model-transport-recovery.md)
• Provider permit 只覆盖一次真实 stream iterator，必须在 error、EOF 或 consumer return 后释放，再进行 retry backoff、circuit wait 或 fallback；跨重试持有 permit 会造成自锁和饥饿 (packages/cli/src/services/PiAIChatService.ts)
• Provider 队列先按 foreground/background/internal 排序，再按 root owner round-robin；aging 会提升长期等待的 internal 请求，但不会改变其 pending class 计费 (packages/cli/src/services/pi/providerRequestAdmission.ts)
• Browser 操作 gate 是单 Session 严格 FIFO，不区分只读与写；关闭会中止 active operation 并拒绝全部 queued operation，调用方必须等待 close() 返回再释放 Context (packages/cli/src/browser/BrowserOperationGate.ts)
• BrowserProcessPool 的 launch failure 不缓存，意外断连会递增 generation 并使所有现有 lease 失效；旧 lease 的迟到 release 不得关闭新一代 Browser (packages/cli/src/browser/BrowserProcessPool.ts)

Architecture

• Runtime、Task、Tool、Provider 和 Browser 各自拥有与故障域匹配的准入器：Session 用 reservation/lease，Task/Provider 用 ticket/permit，工具另加批内 barrier，Browser 另加 Context pool (packages/cli/src/agent/runtime/SessionRuntimeResidency.ts, packages/cli/src/services/pi/providerRequestAdmission.ts)
• 进程级公平调度以 Session 或 root owner 为轮转单位，局部受阻的队首不会阻塞其他 eligible owner；取消和释放都会立即重新 drain (packages/cli/src/tools/execution/ConcurrencyScheduler.ts, packages/cli/src/services/pi/providerRequestAdmission.ts)
• Surface egress 将内存上限、单 writer、写超时和关闭传播集中在通用队列，SSE、ACP 与 Headless 只负责各自的编码和 replay 语义 (packages/cli/src/utils/BoundedSerialEgress.ts, packages/cli/src/server/OrderedSseEgress.ts)

Decisions

• 输出背压采用断开慢消费者而不是丢事件，因为 committed 事件顺序和完整性高于维持单个慢连接；其他订阅者不受影响 (packages/cli/src/server/OrderedSseEgress.ts, git:1af43232)
• 工具并发同时保留 process total、Session total 和 kind 上限，避免一个 Session 或大量 readonly 调用挤占全部 execute/write 容量 (packages/cli/src/tools/execution/ConcurrencyScheduler.ts, git:527cb02b)
• Provider 准入使用 failure-domain 与 root-owner 双重隔离，并给 foreground 保留容量；这是为了让后台子任务和内部采样不能放大上游故障 (packages/cli/src/services/pi/providerRequestAdmission.ts, git:852c8cba, git:471f90f0)

Branching Behavior

• Session Runtime 容量满时，Web reservation 可先回收最旧 eligible resident；ACP reservation 直接返回 typed capacity error，不改变任何已有 Session (packages/cli/src/agent/runtime/SessionRuntimeResidency.ts)
• Task scheduler paused 时即使有 active slot 也排队；resume 或提高并发限制会按 FIFO drain，降低 byte limit 不会驱逐已经接受的等待项 (packages/cli/src/agent/runtime/TaskRunScheduler.ts)
• Tool shared 调用只在队首连续 shared 区间并发；遇到 exclusive 后，后续 shared 不能越过该屏障 (packages/cli/src/tools/execution/ToolConcurrencyGate.ts)
• Provider foreground 排在较新的 background/internal 前，但每 30 秒 aging 一级，长期 internal 最终可提升到 foreground rank (packages/cli/src/services/pi/providerRequestAdmission.ts)
• SSE fresh 连接按 callback 到达顺序释放初始化缓冲，带 replay 的连接改按 committed seq 排序且只发送高于 replay 水位的事件 (packages/cli/src/server/OrderedSseEgress.ts)
• Browser Context 数量达到上限时拒绝新 Session，不会抢占已有 Context；同一 Context 内的页面操作则进入有界串行队列 (packages/cli/src/browser/BrowserProcessPool.ts, packages/cli/src/browser/BrowserOperationGate.ts)
• 进程自然退出会释放 OwnedProcessTree 所有权；durable admission gate 则可设置 releaseOnExit: false，直到独立确认整个进程组已清理才释放 (packages/cli/src/utils/process/CommandAdmissionGate.ts, packages/cli/src/utils/process/OwnedProcessTree.ts)