qwen-code ACP Session 初始化超时取消机制：从 Bridge 到 Agent 的 Deadline 全链路设计与实现

qwen-code ACP Session 初始化超时取消机制从 Bridge 到 Agent 的 Deadline 全链路设计与实现【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文基于 qwen-code 仓库的 ACP session initialization deadline 设计文档深入剖析守护进程daemon与 ACP Agent 之间会话初始化超时init_timeout的完整治理方案。该方案解决了一个经典的一致性难题当newSession超时后子进程内的初始化仍可能继续完成从而产生 Bridge 无法感知的幽灵会话。读完本文你将掌握 qwen-code 如何通过绝对时间戳 Deadline、AbortSignal传播、晚到结果兼容生命周期与故障隔离语义把一次会话创建失败收敛为干净、可控的资源清理并了解其对应的源码实现与测试验证路径。问题背景wrapper 超时与子进程真实状态的分裂旧实现的缺口设计文档 acp-session-initialization-deadline.md 明确指出daemon 对newSession是有超时约束的init_timeout但历史上的超时只拒绝了 Bridge 包装层wrapperACP 请求本身仍在子进程内继续执行。后果链如下一个缓慢的SessionStart命令钩子hook在调用方已经收到init_timeout之后才结束子进程因此发布了一个真实的 child Session但 Bridge 从未注册过它该钩子的后代进程或其他会话资源随之存活形成资源泄漏。为什么不能简单杀掉通道文档强调这既不同于 ACP 通道整体拆除一个共享通道可能拥有健康的兄弟 Session因一次失败创建而杀掉通道会造成无关会话丢失也不同于此前 HookRunner 与 ACP 进程树修复那些修复提供了树感知的取消与通道清理能力但都没有决定会话初始化何时该被取消。因此需要一个新的、位于初始化链路上的决策点。设计目标定位该变更使Bridge 已有的初始化预算budget对标准可信 daemon→ACP 路径具有权威性让谁启动的初始化来决定何时取消初始化同时保持对外公开 API 不变——外部调用方仍然只看到init_timeout失败内部私有 deadline 与子进程错误类型不会暴露为 HTTP 或 SDK 字段。Deadline 契约绝对时间戳而非相对超时_meta中的私有字段Bridge 在真正派发 ACP 请求之前会向_meta写入qwen.daemon.sessionInitializationDeadlineMs字段。在源码中该字段的常量定义位于 packages/acp-bridge/src/bridgeTypes.tsexport const SESSION_INITIALIZATION_DEADLINE_META_KEY qwen.daemon.sessionInitializationDeadlineMs; export const SESSION_INITIALIZATION_TIMEOUT_ERROR_KIND session_initialization_timeout;其值不是相对毫秒数而是由配置的initializeTimeoutMs推导出的绝对 Unix 时间戳。实际写入发生在 packages/acp-bridge/src/bridge.ts[SESSION_INITIALIZATION_DEADLINE_META_KEY]: Date.now() initTimeoutMs,设计文档解释了选择绝对时间戳的动机绝对 deadline 可防止序列化、传输和子进程调度耗时在每一层意外地重新赋予一个全新的完整预算。如果传递相对超时值每一层等待都可能重新计时最终总等待时间远超预期。可信调用方门槛并非任何 ACP 调用方都能通过请求元数据取消初始化只有完成了私有 managed-parent 能力握手的 ACP Agent 才能读取该字段不受信任的或 standalone ACP 调用方无法利用请求元数据触发取消可信值必须是正的安全整数positive safe integer且在 Node 支持的定时器范围内畸形值会在任何设置或会话状态创建之前直接失败。对应实现见 packages/cli/src/acp-integration/acpAgent.ts 中的createSessionInitializationDeadlineif (raw undefined || !this.isTrustedManagedParent()) return undefined; if (typeof raw ! number || !Number.isSafeInteger(raw) || raw 0) { throw RequestError.invalidParams( { errorKind: invalid_session_initialization_deadline }, \_meta[${SESSION_INITIALIZATION_DEADLINE_META_KEY}]\ must be a positive safe integer, ); } const remainingMs raw - Date.now(); if (remainingMs 2_147_483_647) { throw RequestError.invalidParams( { errorKind: invalid_session_initialization_deadline }, \_meta[${SESSION_INITIALIZATION_DEADLINE_META_KEY}]\ exceeds the supported timer range, ); }注意2_147_483_6472³¹−1正是setTimeout在 Node 中的最大延迟上限超过它定时器会立即触发——这也是 packages/core/src/config/config.test.ts 中拒绝AbortSignal.timeout无法接受的取值小数、超过 2³¹−1、非有限数测试所守护的边界。请求级 AbortControllerAgent 持有一个请求作用域request-scoped的AbortController定时器是unreferenced不阻止进程退出的并在finally中清除若剩余时间已 ≤ 0立即以超时错误 abort信号不会存储在最终生成的 Session 上因此无法用于取消后续轮次turn。const controller new AbortController(); const timeoutError new RequestError( ACP_ERROR_CODES.INTERNAL_ERROR, Session initialization deadline exceeded, { errorKind: SESSION_INITIALIZATION_TIMEOUT_ERROR_KIND }, ); let timer: NodeJS.Timeout | undefined; if (remainingMs 0) { controller.abort(timeoutError); } else { timer setTimeout(() controller.abort(timeoutError), remainingMs); timer.unref(); } return { signal: controller.signal, dispose: () { if (timer) clearTimeout(timer); }, };超时配置的校验Bridge 侧的initializeTimeoutMs同样有严格的入参校验位于 packages/acp-bridge/src/bridge.ts必须为正整数且不超过受支持的定时器范围默认值为DEFAULT_INIT_TIMEOUT_MS 10_000见同文件 第 2675 行即默认 10 秒。取消传播路径信号如何走完初始化链路从 newSession 到 HookRunner 的完整链路设计文档给出了信号遵循的既有初始化所有权路径ACP newSession - Config.initialize - GeminiClient.initialize - startChat - SessionStart HookSystem - HookRunner各层职责如下Config在注册初始化状态之前、以及每个 await 的初始化阶段之后检查取消GeminiClient将信号传入SessionStart在钩子结果返回后检查信号并重新抛出rethrowabort 原因而不是套用钩子普通的 best-effort 错误策略——这是必需的因为 HookSystem 可能把取消聚合进一个结果而不是直接抛出QwenAgent在将新 Session 发布进自己的 session 映射之前再次检查信号。错误种类与对外映射当子进程报告私有的session_initialization_timeout错误种类时Bridge 将其映射回既有的公开契约BridgeTimeoutError(newSession)。在 packages/acp-bridge/src/bridge.ts 中可以看到这个映射逻辑if ( extractJsonRpcErrorField(error, errorKind) SESSION_INITIALIZATION_TIMEOUT_ERROR_KIND ) { recordNewSessionPublicTimeout(ci, requestedSessionId); reject(new BridgeTimeoutError(newSession, initTimeoutMs)); } else { reject(error); }为什么不做整体竞速文档特别解释了**不把整个 Config 初始化与一个 reject 的 wrapper Promise 竞速race**的原因那样会让清理逻辑与仍持有同一 Config 的初始化代码并发执行。正确做法是没有 AbortSignal API 的操作正常完成随后紧跟一个取消检查点checkpointBridge 的兼容生命周期始终作为最外层兜底边界。这一阶段完成 检查点模式在 packages/core/src/config/config.test.ts 中有对应测试既验证预中止的初始化在不消耗 Config 的情况下被拒绝也验证初始化中途信号被中止时以 abort 原因拒绝测试中通过监听signal的abort事件并在signal.reason上 reject 来模拟。晚到结果兼容滚动升级期间的护栏为什么需要兼容层Bridge 的公开定时器触发后仍会观察原始 ACP 请求——这是为了保护滚动升级期间尚未消费私有 deadline 的旧版 Agent。晚到结果分三种情况处理晚到结果类型Bridge 处理晚到失败late failure释放 hidden-work 计数与调用方提供的 ID fence晚到成功late success永不注册。Bridge 对返回的 Session ID 发送一次有界bounded的qwen/control/session/close且只接受closed: true作为清理完成的证明资源不存在resource-not-found视为清理已完成对应实现可见 packages/acp-bridge/src/bridge.ts晚到成功后调用settleAbandonedNewSession(ci, abandonedToken, value.sessionId, requestedSessionId)进行清理并结算。通道级隔离失败不扩散close 失败只隔离该通道上的新增会话准入已有兄弟 Session 继续运行直到排空drain之后通道才被回收原始请求在额外一个初始化预算内仍未settle通道同样拒绝新 Session直到请求 settle 或通道排空空通道超时走既有的立即拆除路径共享通道在仍有兄弟 Session 时绝不因一次超时被杀掉。实现中相关的两个机制是armNewSessionSettlementGracebridge.ts与recordNewSessionPublicTimeout。前者用于在有兄弟会话时启动宽限期后者记录公开超时并判断通道是否已空。资源预留的持有规则Bridge 在原始请求与清理完全 settle 之前持续持有新会话准入预留和调用方提供的 ID 预留被遗弃的请求计入maxSessions上限通道拆除启动后shutdown 会等待这些请求的结算settlement。这防止了重试过度提交资源、或回收一个晚到子响应仍可能创建的 ID——对应 acpAgent.ts 中的reserveStartingSessionId同一 sessionId 若已被预留startingSessionIds中已存在会直接抛出session_id_conflict只有显式释放后该 ID 才能被复用。失败语义与故障边界设计文档为整个机制定义了清晰的失败契约可总结如下公开面一致新 Agent 执行的 deadline 与旧 Agent 的 wrapper 超时最终都以既有的公开初始化超时呈现正常的初始化失败保持不变。绝不发布超时会话超时的 Session永远不会插入 Agent 或 Bridge 的 session 映射。兄弟会话不受影响共享通道上已存在的 Session 在晚到结算与清理期间保持可用。失败闭环清理不确定性对新建会话是 fail-closed拒绝但不会扩大为 daemon 级或兄弟会话级终止。通道退出兜底通道退出通过既有的 transport-close 竞速race结算被遗弃的工作。非目标Non-goals文档同时划定了明确的边界避免过度设计不改变已配置的初始化超时也不增加 per-endpoint deadline不取消 load/resume、prompt 执行、认证 API、MCP discovery API 或任意扩展初始化不改变 HookRunner 超时默认值或 HookRunner 进程所有权不把 ACP 进程组清理替换为 cgroups、Windows Job Objects 或其他 OS 级 supervisor不改变 standalone 绑定、会话所有权、Bridge 路由或 HTTP 响应形状。验证与测试覆盖设计文档要求通过以下手段验证该机制仓库中已有对应实现与测试基线复现共享通道的第二个newSession先超时、后成功——复现子进程创建了 Bridge 看不到的 Session的原始缺陷Bridge 行为验证发送绝对 deadline、保留公开超时类型、关闭晚创建 Session、保持兄弟 Session 存活、围栏fence请求 ID、将遗弃工作计入上限、在清理失败或超期未结算时隔离新准入Agent 行为验证只有可信 managed parent 能激活 Agent 侧 deadline且 abort 必须在 Session 发布前拒绝信号转发验证Gemini 初始化将信号传入SessionStart且不把取消当作普通钩子失败吞掉——对应 config.test.ts 中初始化 deadline 超时以 abort 原因为结果的用例回归矩阵运行受影响的 Bridge、Agent、Config/client、HookRunner 与进程树测试随后执行 build、typecheck、lint、format 与 clean-diff 审计。关键源码地图关注点源码位置Deadline 元数据键与错误种类常量packages/acp-bridge/src/bridgeTypes.tsBridge 侧超时配置校验与默认值packages/acp-bridge/src/bridge.ts、L2963-L2978Bridge 写入绝对 deadlinepackages/acp-bridge/src/bridge.tsBridge 公开定时器与晚到结果结算packages/acp-bridge/src/bridge.ts错误种类映射回 BridgeTimeoutErrorpackages/acp-bridge/src/bridge.tsAgent 侧 deadline 解析与 AbortControllerpackages/cli/src/acp-integration/acpAgent.ts请求 ID 预留ID fencepackages/cli/src/acp-integration/acpAgent.ts初始化取消相关测试packages/core/src/config/config.test.ts、L5446-L5501结语qwen-code 的 ACP session initialization deadline 机制本质上是把超时从一层包装 Promise 的拒绝升级为贯穿 daemon→Bridge→Agent→Config→GeminiClient→HookRunner 整条初始化链路的可取消所有权模型。它以绝对时间戳消除了分层计时的累积误差以 AbortSignal 实现了纵深传播又以晚到结果兼容生命周期守住了滚动升级与并发兄弟会话的安全边界。这种预算权威化 故障局部化的设计为长生命周期 AI Agent 的会话资源治理提供了一个值得借鉴的工程范式。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考