[bug][agent-loop] steer 在阻塞式 job_output(wait) 期间无法抢占:next-step 只在 step 边界消费,会话最长 10 分钟对用户输入无响应(0.1.5-alpha.1 实测)

[TT-Wang]

在 0.1.5-alpha.1 上确认:一次阻塞式 job_output(wait: true) 期间,用户的 steer 消息要等这次 wait 返回才会被消费,最长 10 分钟。会话在这段时间里对输入完全没有反应,UI 上只显示「深度求索中...」,看起来像卡死,实际进程健康、后台任务也在正常推进。

这不是「跑等待命令就该失联」。steer() 的语义是插队到 next-step,本应尽快被消费;问题在于 next-step 的消费点只有 step 边界一处,而一次 wait 可以让 step 边界十分钟不出现。同一状态下 agent.cancel({kind:'user'}) 能在同一 tick 内解除阻塞,说明等待逻辑本身是尊重 AbortSignal 的,只是 steer 从来不会去触发它。

实测

dsh-v0.1.5-alpha.1(commit 5dda764ed3,源码构建),隔离的 DSH_HOME,macOS / Node v22.22.3:

时刻	事件
7.0s	agent 阻塞在 job_output(wait: true),后台 job 是 sleep 120
10.1s	经 session/prompt 以 mode: 'steer' 发一条带唯一标记的消息
125.8s	该消息才作为 user/message 进入会话日志

steer 延迟 115.7 秒,正好等于剩余的 wait 时间。

代码路径(行号为 0.1.5-alpha.1)

steer 只入队,不 abort — packages/core/agent-loop/src/agent.ts:141-143

steer(input: UserMessage): void {
  this.send(input, 'next-step', true)
}

对照 cancel,它会 abort 当前 phase — agent.ts:154

if (this.phase.kind !== 'idle') this.phase.abort.abort(cause)

而 next-step 的唯一消费点在 preStep() 里 — agent.ts:244

const claimed = this.inbox.claim(target, position.turn)

step 卡在 await 里就永远走不到这一行。阻塞侧本身没有问题:packages/jobs/tool-jobs/src/index.ts:332-333 正确 clamp 了超时并把 exec.signal 转发下去,packages/jobs/jobs-local/src/index.ts:230 的 wait 也确实只有三个出口(job 终态、timeout、signal abort)。缺的是第四个出口。

配置上有个容易混淆的地方(tool-jobs/src/index.ts:205-206):默认阻塞是 30 秒,不是 10 分钟;10 分钟是 maxWaitTimeoutMs 上限。但模型可以显式把 timeout_ms 顶到上限,没有任何机制阻止或抢占。

tool-jobs 的 system prompt 里已经写了「do not busy-poll or sleep on one」,现场会话仍然在做 sleep + job_output(wait:true) 的组合轮询。靠提示词约束模型行为在这里不成立,需要机制层面的兜底。

顺带一提,job 完成通知走的是同一条路(tool-jobs/src/index.ts:292-299,owner busy 时 inject,即 next-step),所以完成通知的延迟特征和用户输入完全一致。

版本核对

这个问题最初是在 0.1.3-alpha.2 上遇到的。升到 0.1.5-alpha.1 后逐条复核,上述判据字节级未变;git diff dsh-v0.1.3-alpha.2..dsh-v0.1.5-alpha.1 里 tool-jobs 和 jobs-local 两个包零改动。agent.ts 改了 111 行,但都是本版 Inbox 重构的搬家,没有触及 steer / claim / abort 的语义。全仓搜 preempt / interrupt / pendingInput 也没有新增的抢占路径。

想讨论的修法

首选是协作式抢占:让 ctx.jobs.wait 除了 job 完成和 timeout 之外,也在「调用方有 pending next-step 输入」时 resolve,返回 [status: running] 并保持 job 存活。语义不变、不丢工作、job 继续跑,只是把控制权还给 loop。实现上需要给 wait 传一个 until / input-pending 信号。

次选是收紧上限加界面提示:把 maxWaitTimeoutMs 默认从 10 分钟降到 60–120 秒,同时在界面上显示「会话正阻塞于 job X,你的消息已排队」,至少别让用户误判成卡死。

还有一个更激进的选项:仅针对阻塞式 wait,把用户 steer 当作软中断,复用现有 abort 路径但不清空 inbox。这个改动面最大,语义上也最需要斟酌。

有意思的是,0.1.5 把 Inbox 改成类型接口之后,hasPending / claim 退出了公开面,但公开的 Inbox 保留了 nextStep 只读数组(packages/core/agent/src/runtime-types.ts:48-52),Agent.inbox 也是公开的,工具执行上下文能拿到 exec.agent。所以第三方插件现在已经可以包一层 job_output、轮询 exec.agent.inbox.nextStep.length 来先行验证首选方案的语义,不必等本体改动。

想问维护者两件事:一是首选方案的语义(wait 因为有排队输入而提前返回 running)是否可接受;二是如果可接受,这个「input-pending」信号更适合由 loop 通过 exec 传给工具,还是由 jobs 服务自己去问 agent。

临时缓解

杀掉底层子进程(比如 sleep 的 PID),job 立即结束,wait 返回,会话回到 step 边界后就能消费排队的消息。

[argszero]

@TT-Wang 你的 #6030 我把代码路径逐行核过（master 5dda764，0.1.5-alpha.1），诊断全对——steer 只入队不抢占、next-step 消费点只有 step 边界一处、job_output 的 wait 只有三出口。另外你的「插件可以先行验证首选方案」判断也成立，而且现有的 in-tree wrapper 就是现成模板。以下补三处源级事实 + 对两个设计问题的回答。

① 源级确认（与你的行号一致）

• steer(input) = this.send(input, 'next-step', true)（agent-loop/agent.ts:141-143），只入队，不碰 phase；cancel 才 this.phase.abort.abort(cause)（:154）——语义分叉如你所述。
• next-step 唯一消费点 preStep() 的 this.inbox.claim(target, position.turn)（:244）——step 卡在 await 里确实走不到。
• jobs.wait（jobs-local/index.ts:230-268）：三出口 = job 终态（resolve）/ 超时（TASK_WAIT_TIMEOUT 分码后 resolve）/ signal abort（wait aborted reject）。abort 路径只 uncount() waiter，不杀 job——job 继续跑，只是没人等它。这跟你观察的「cancel 同一 tick 解除阻塞、job 存活」完全一致。

② 插件先行验证——seam 已存在，且有官方模板

ctx.on('tools/execute', async (exec, next) => ...) 是公开 around-wrapper seam，官方 @deepseek-ai/dsh-tool-call-timeout-policy（packages/guard/timeout-policy/src/index.ts:56-80）就是模板：

ctx.on('tools/execute', async (exec, next) => {
  // ... 判定是否目标工具
  const upstream = exec.signal
  exec.signal = d.signal          // 用派生 signal 替换
  try { return await next() }
  finally { exec.signal = upstream }   // 还原，post-execute 监听者看不到
})

它证明了「wrapper 可以临时替换 exec.signal 并结构化替换结果」。所以你要的「wait 因 pending 输入提前返回 running、job 存活」完全可以在插件层实现：

• wrapper 匹配 job_output 且 args.wait === true；
• 派生一个组合 signal（AbortSignal.any([exec.signal, pendingInput.signal])）替换 exec.signal；
• 用一个低频率轮询（或更好：监听用户消息事件）在 exec.agent.inbox.nextStep.length > 0 时触发 pendingInput.abort()；
• 内层 jobs.wait 走 abort 出口 reject 后，wrapper 结构化替换成非错误结果，比如 wait interrupted by pending user input; job <id> still running（job 未死，可再 job_output 读），而不是把 wait aborted 错误透传给模型；
• 区分来源：pendingInput.signal.aborted 为真 → 替换结果；exec.signal.aborted 为真 → 透传（保持 cancel 语义）；都不是 → 透传原结果。

这不需要等本体改动，且能实测验证首选方案的语义是否被模型正确消化（模型拿到 "interrupted, still running" 后是去读 job 还是去回应用户）。你提的 exec.agent.inbox.nextStep 公开只读数组（core/agent/runtime-types.ts:48-52）就是这个触发条件的来源。

③ 对两个设计问题的回答

Q1：wait 因排队输入提前返回 running 是否可接受？

可接受，且语义上最干净——但有一个必须明确的判别：wait 提前返回时，那次「排队输入」必须仍留在 inbox 里由后续 preStep claim，wait 只是把控制权还回去，不能吞掉输入。你首选的协作式抢占天然满足（它只 resolve wait，不碰 inbox）；次选（steer 转软中断走 abort 路径）要小心别把 inbox 清了（cancel() 默认清 inbox，软中断必须 keepInbox）。这是「协作式」和「激进式」的分水岭。

Q2：input-pending 信号由 loop 经 exec 传给工具，还是 jobs 服务问 agent？

倾向前者（loop 经 exec 传给工具），理由：

1. 归属：input-pending 是 agent 循环的状态（inbox 属于 agent），不是 jobs 服务的状态。jobs 服务去问 agent 会引入反向依赖（jobs 是能力提供方，不该知道调用方的 inbox 语义）；而 exec 本来就是 loop 派发给工具的上下文，往里加一个只读视图（如 exec.pendingInput: boolean 或更通用的事件订阅点）是单向的。
2. 演进：loop 侧将来若支持「steer 也 abort 长等待」的统一抢占，信号源都在 loop；jobs 只需保持「wait 尊重 signal + 新增的 until/input-pending 谓词」即可，不感知 agent 类型。
3. 与现有 seam 一致：exec.signal 已经是 loop 派发下来、工具必须尊重的东西；加一个同源只读谓词是同一方向的自然延伸。

不过插件先行版不需要等这个设计定案——插件版直接在 wrapper 里轮询 exec.agent.inbox.nextStep，就等效于「loop 经 exec 传信号」的早期形态，正好用来验证 Q1 的语义是否成立。

附带：完成通知走同一条路的意义

你说 job 完成通知（owner busy 时 inject 即 next-step）延迟特征与用户输入一致——这意味着这个 bug 也吞 job 完成通知：模型在 wait 期间 job 早就做完了，但通知要等 wait 到期才到。所以这个修复同时改善「job 完成 → 模型知道」的延迟，不只是用户输入体验。插件版 wrapper 顺带把这个也解决了（pending 输入触发时若 job 已 terminal，直接读快照返回终态即可）。

一句话：首选方案语义成立、信号源应在 loop 侧；插件先行版现在就能做，官方 timeout-policy 是现成模板，我可以按上面设计实现一版发布，实测首选语义后再回传数据给 upstream 定案。

[argszero]

插件形态方案已发布，来闭环这个缺口：

@argszero/cordis-plugin-steer-preempt v0.1.0（npm：npm install @argszero/cordis-plugin-steer-preempt；源码：https://github.com/argszero/cordis-plugin-steer-preempt ）

机制（完全按本串核实的代码路径实现）：

• tools/execute around-wrapper（与 in-tree guard/timeout-policy 同一接缝），只对 job_output + wait: true 生效，其余工具调用零开销直通；
• 阻塞期间轮询 agent 公开的 inbox.nextStep 只读队列（只读不消费——消费权仍在 loop 的 preStep claim）；
• 发现排队 steer 后留 ~1s settle grace（让恰好要结束的 job 走正常路径返回真结果），然后 abort 派生 AbortSignal——caller/turn 信号不动，真正的 cancel 语义不受影响；
• abort 使 jobs.wait 提前 reject（waiter uncount、job 不被杀），step 结束 → 到达 step 边界 → steer 被消费；
• 结果替换判别：只有「自己触发 abort 且结果为 isError」才换成结构化 STEER_PREEMPTED 结果（告诉模型 job 仍在后台、用户消息已排队、勿再发起阻塞 wait）；grace 内 job 完成 → 真结果原样透传。

验证：8 个行为测试（node:test，fake dispatch 模拟 registry 把 'wait aborted' throw 转 isError result 的语义）全过；peer 依赖 dsh-tools >=0.1.2，在 0.1.5-alpha.1 上做的源级核对。

若 core 将来把 next-step 消费从「仅 step 边界」提前到 step 内（比如 tool 结果回环前查一次 inbox），此插件即可退役——在那之前它是纯插件侧的补丁，不动 harness 一行代码。作者若想直接复刻成 in-tree 修法，这个实现也可作参考。

[TT-Wang]

@argszero 谢谢核实。你引的两处我也独立对过 dsh-v0.1.5-alpha.1:packages/guard/timeout-policy/src/index.ts 的 wrapper 形态确实是现成模板(换 exec.signal、finally 还原、只在自己计时器触发时替换结果),jobs-local/index.ts:255-268 的 abort 出口也确实只 uncount() 后 reject,不杀 job。

你补的 keepInbox 是对的,而且树内已有先例

这条我们报告里漏了。补一个证据:session-controller 自己的取消路径就是这么写的——packages/api/session-controller/src/commands.ts:509

agent.cancel({ kind: 'user' }, { keepInbox: true })

所以「软中断复用 abort 路径但不清 inbox」不是新发明,API 层的 cancel 本来就保 inbox。第三个方案(激进式)的顾虑因此比我原先写的要小。

你插件里有个边界:steer 和 inject 共用同一条队列

Agent.inbox.nextStep 装的不只是用户 steer。agent.ts:141-147:

steer(input)  { this.send(input, 'next-step', true)  }
inject(input) { this.send(input, 'next-step', false) }

两者进的是同一条 next-step 队列,interrupt 标志是 send 的参数,不落在消息上,所以从 nextStep 本身分不出来。

而 job 完成通知在 owner busy 时走的正是 inject——tool-jobs/src/index.ts:298 owner.inject(message)。

后果:agent 阻塞在 job A 的 wait 上时,job B 完成就会把通知塞进 nextStep,你的 nextStep.length > 0 触发,grace 过后 abort,模型收到的 STEER_PREEMPTED 文案却是「a new user message arrived」「The user message is queued」——此时并没有任何用户输入。

好在可以区分。用户经 session/prompt 来的消息带 source.kind === 'user'(commands.ts:330-334),而完成通知带的是 { kind: 'plugin', plugin: 'tool-jobs', form: 'notice' }(tool-jobs/src/index.ts:280-287)。把触发条件从 .length > 0 换成按 source.kind === 'user' 过滤即可。

顺带:被 inject 的完成通知本身也卡在同一个 step 边界后面,所以「job B 完成了但模型要等 job A 的 wait 到期才知道」这个延迟是真实存在的。要不要顺手也让它抢占,是个产品选择——但那种情况下的文案得换一套说法,不能说用户在等。

还需要维护者定的

目前串里还没有官方的人表态。真正只有他们能决定的是那个信号归属:input-pending 该不该作为只读谓词进 exec(和 exec.signal 同源同方向),还是留在插件层各自轮询。你我在这点上判断一致,但这决定了将来是插件长期存在还是退役,值得他们给个方向。

[argszero]

@TT-Wang 你这条反馈非常及时而且完全正确——你等于在我发布的 steer-preempt 插件里挑出了一个真实 bug。那个 inject/steer 共队列的问题我 v0.1.0 确实没接住，我已经 修复并发布 v0.1.1：

@argszero/cordis-plugin-steer-preempt@0.1.1（仓库 https://github.com/argszero/cordis-plugin-steer-preempt，npm latest=0.1.1）

根因：Agent.inbox.nextStep 这条队列确实被两个生产者共用——agent.steer(input)（用户输入，send('next-step', true)）和 agent.inject(input)（插件注入通知，比如 job B 完成时 tool-jobs/src/index.ts:298 的 owner.inject(message)，send('next-step', false)）。interrupt 标志是 send 的参数，不落在消息上，所以从 nextStep 本身分不出来的。我 v0.1.0 的触发条件是 nextStep.length > 0，于是「模型阻塞在 job A 的 wait 上时，job B 一完成就把通知塞进 nextStep，我误判成用户 steer 就去 abort 了」——这正是你指出的 false positive。

修复：把触发条件从队列长度改成逐条 message.source.kind === 'user'。你给的判别依据我全部源级核对过：

• 用户经 session/prompt 来的消息带 source.kind === 'user'（commands.ts:330-334）；
• 完成通知带 { kind: 'plugin', plugin: 'tool-jobs', form: 'notice' }（tool-jobs/src/index.ts:280-287）。

所以现在只有真实 user steer 会触发抢占；plugin 通知即使塞在同一个队列里也不会误 abort job A 的 wait（那本质上不是用户输入，不该折损模型正在等的那个 job）。

加了两个回归测试（共 10/10 通过）：

1. 队列里只有 plugin notice → 不抢占，wait 正常 resolve，返回真实结果；
2. 队列里同时有 notice + user steer → 只有 user steer 触发抢占。

关于「job B 完成也该抢占吗」

你在信里提的那个产品选择我很认同：被 inject 的完成通知因为卡在同一个 step 边界后面，确实存在「job B 完成了但模型要等 job A 的 wait 到期才知道」的延迟。但那应不应该抢占，我觉得不该由这个插件在 v0.1 决定——因为它需要另一套文案（不能说「用户在等」，而是「job B 已完成」），语义和目标不同。这更适合作为下一步的独立增强，或者干脆在官方定夺 signal 归属后处理。

关于需要维护者定的信号归属

你我的判断一致：input-pending 该不该作为只读谓词进 exec（和 exec.signal 同源同方向），决定将来这是长期插件还是能退役。这确实是只有官方能定的。我这边插件已经按「保守、只在真实 user steer 时抢占」落地，等前几轮你提到的官方表态即可。

再次谢谢你把边界挑到这一层——这是「讨论 → 插件 → 发现真 bug → 回源修复」最完整的一次闭环。如果 v0.1.1 的默认行为（pollMs 200 / graceMs 1000，只拦 job_output(wait:true)）你觉得还需要调，直接在仓库开 issue 或 @我。

[argszero]

@TT-Wang 补一条更正 —— 我上一条公告的 v0.1.1 其实装不上，请用 v0.1.2。

问题：v0.1.1 声明 @deepseek-ai/dsh-tools peer range 为 >=0.1.2，而它匹配不到任何已发布版本。原因是 semver 的 prerelease 元组规则：一个 comparator 只放行与它自己 major.minor.patch 元组相同的 prerelease。dsh 当前所有发布都是 prerelease，0.1.2-rc.1 低于 0.1.2 被排除，0.1.5-* 元组是 0.1.5 也被排除 —— 结果 = 空集，npm install 直接 ETARGET。

v0.1.2 已发布，range 改为一条 comparator 对应一条元组线：

>=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0

实测（空项目装 npm pack 的 tarball，不加 --legacy-peer-deps）：无预装 / dsh-tools@0.1.2-rc.1 / dsh-tools@0.1.5-rc.1 三种都通过；对照组 v0.1.1 直接 ETARGET。并加了 test/peer-range.test.js 回归，防止这种 range 再回来。

你提的功能修复一行没动 —— 触发条件仍是逐条 message.source.kind === 'user'（plugin 通知不再误抢占），那两个回归测试也都在。所以如果你在 0.1.2-rc.1 上实测，直接装 @argszero/cordis-plugin-steer-preempt@0.1.2（先 npm view 确认看到 0.1.2 再装，避开 CDN 缓存）。

顺带：同一个坑我复核了自家全部插件，thinking-loop-guard 与 llm-tool-call-guard 同病，均已修复发布（0.1.3 / 0.1.3）。如果你自己在写 dsh 插件的 peer/dependency，别用 ^0.1.x / >=0.1.x 这类形式 —— 用 node-semver 的 satisfies 对你要支持的真实版本逐个断言最稳。

[TT-Wang]

补一条相关:同一个函数的另一个缺口我单独发在了 #6285。job_output(wait: true) 同样不认「有新输出」,流式任务读进度要睡满超时。

这里缺的是「有排队输入就醒」,那边缺的是「有新输出就醒」,都在 jobs-local 的 wait 里。#6285 提的 P1b 给 wait 加 until,如果把 input-pending 也纳入,这个串的问题可以一起收掉。

#1542(任务挂死时 wait 超时只回 [status: running]、没有活性信号)也在同一片区域,可以一并参考。