pi-legion 0.16.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +117 -0
- package/CONTRIBUTING.md +109 -18
- package/README.md +389 -630
- package/agents/advisor.md +7 -5
- package/agents/centurion.md +53 -0
- package/agents/designer.md +33 -33
- package/agents/planner.md +1 -2
- package/agents/prototype.md +2 -2
- package/agents/reviewer.md +66 -31
- package/agents/scout.md +6 -2
- package/agents/worker.md +11 -3
- package/docs/contracts/esc-abort-v1.md +131 -0
- package/docs/contracts/esc-cascade-v2.md +101 -0
- package/docs/design.md +73 -37
- package/docs/legion-v2-contract.md +461 -0
- package/docs/legion-v2-delivery.md +62 -0
- package/docs/retire-hardening-contract.md +125 -0
- package/docs/subagents-teams.md +76 -0
- package/docs/tui-viewer-contract.md +276 -0
- package/docs/vexillatio-contract.md +162 -0
- package/index.ts +1568 -288
- package/package.json +19 -12
- package/skills/pi-legion/SKILL.md +86 -94
- package/src/agents/agents.ts +66 -16
- package/src/agents/overrides.ts +2 -1
- package/src/agents/paths.ts +1 -1
- package/src/agents/settings.ts +268 -20
- package/src/api.ts +49 -48
- package/src/{herdr → backends/legacy}/client.ts +14 -69
- package/src/{shared → backends/legacy}/cursor-chat.ts +2 -2
- package/src/{herdr → backends/legacy}/runner.ts +22 -9
- package/src/backends/legacy/types.ts +138 -0
- package/src/extension/auto-doctor.ts +144 -0
- package/src/extension/budget.ts +2 -2
- package/src/extension/child-guard.ts +214 -201
- package/src/extension/event-bus.ts +263 -0
- package/src/extension/legion-commands.ts +773 -0
- package/src/extension/legion-doctor.ts +975 -0
- package/src/extension/legion-status.ts +172 -0
- package/src/extension/legion-stop.ts +150 -0
- package/src/extension/legion-tools.ts +816 -0
- package/src/extension/notify.ts +24 -19
- package/src/extension/playbook.ts +20 -89
- package/src/extension/recycle.ts +2 -7
- package/src/extension/runtime.ts +736 -107
- package/src/extension/scout-guard.ts +492 -0
- package/src/extension/slash.ts +89 -438
- package/src/extension/spawn-hints.ts +79 -0
- package/src/extension/summary.ts +17 -58
- package/src/legion/budget.ts +165 -0
- package/src/legion/db.ts +242 -0
- package/src/legion/events.ts +150 -0
- package/src/legion/mail.ts +412 -0
- package/src/legion/nodes.ts +461 -0
- package/src/legion/rebuild.ts +533 -0
- package/src/legion/state-machine.ts +313 -0
- package/src/legion/usage.ts +101 -0
- package/src/runs/acceptance.ts +82 -25
- package/src/runs/args.ts +117 -15
- package/src/runs/hygiene.ts +335 -0
- package/src/runs/orchestrator.ts +808 -1681
- package/src/runs/owner.ts +61 -0
- package/src/runs/provider-pin.ts +59 -0
- package/src/runs/provision.ts +135 -0
- package/src/runs/role-tool-gates.ts +103 -0
- package/src/runs/store.ts +44 -17
- package/src/runs/verify-queue.ts +195 -0
- package/src/shared/name.ts +29 -0
- package/src/shared/output-cap.ts +57 -0
- package/src/shared/progress.ts +57 -135
- package/src/shared/session.ts +280 -173
- package/src/shared/types.ts +115 -208
- package/src/supervisor/child-memory.ts +140 -0
- package/src/supervisor/proc-tree.ts +103 -0
- package/src/supervisor/rpc-supervisor.ts +1033 -0
- package/src/supervisor/types.ts +153 -0
- package/src/supervisor/ui-proxy.ts +226 -0
- package/src/tui/chat-items.ts +330 -0
- package/src/tui/live-overlay.ts +874 -0
- package/src/tui/status.ts +553 -27
- package/src/tui/tree-view.ts +808 -0
- package/src/tui/viz/canvas.ts +119 -0
- package/src/tui/viz/layout.ts +111 -0
- package/src/tui/viz/model.ts +123 -0
- package/src/tui/viz/palette.ts +188 -0
- package/src/tui/viz/panels.ts +532 -0
- package/src/tui/viz/railway.ts +313 -0
- package/src/tui/viz/rate.ts +211 -0
- package/src/tui/viz/view.ts +228 -0
- package/src/extension/parent-label.ts +0 -115
- package/src/profiles/classify.ts +0 -375
- package/src/profiles/profiles.ts +0 -730
- package/src/runs/layout.ts +0 -258
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# ESC 级联关闭契约(v2,2026-10-13 冻结)
|
|
2
|
+
|
|
3
|
+
## 背景
|
|
4
|
+
|
|
5
|
+
v1(esc-abort-v1.md,已随 e66c85f 合入)冻结了「ESC ≠ 杀 children」语义。用户裁决推翻:turn 是 children 的 owner,turn 被 abort 时 children 应级联关闭,否则是资源泄漏。
|
|
6
|
+
|
|
7
|
+
## 冻结决定
|
|
8
|
+
|
|
9
|
+
### A. ESC 打断 turn → 级联优雅关闭 children
|
|
10
|
+
|
|
11
|
+
改动点 `index.ts` 工具 execute(约 :687-691 的 `signal?.aborted` 快速返回处):
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
if (signal?.aborted && action !== "stop") {
|
|
15
|
+
// NEW: cascade-close children owned by this turn before returning.
|
|
16
|
+
await cascadeRetireAll(); // fire-and-forget 也可以,但要保证 promise 存活到 retire 完成
|
|
17
|
+
return ok("interrupted (parent turn aborted)");
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
**注意**:进入 execute 时 signal 已 aborted 的情况(ESC 发生在此工具调用排队后、执行前)——此时本 turn 尚未 launch 过任何 child,cascade 是 no-op,安全。
|
|
22
|
+
|
|
23
|
+
但真正的触发点是**执行中途 abort**:wait/collect 正在 await 时 signal 才 abort。这些路径已有 interrupted 返回分支(waitAction / collectChild / collectInline / waitOne),在这些分支统一调 `cascadeRetireAll()`。
|
|
24
|
+
|
|
25
|
+
### B. cascadeRetireAll 实现(index.ts)
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
const cascadeRetireAll = async (): Promise<void> => {
|
|
29
|
+
// 1. runtime 跟踪的所有 jobs(与 stopAction all:true 相同的目标集)
|
|
30
|
+
for (const name of targets) runtime.cancelWatch(name); // 先停 watch,防 retire 期间通知噪音
|
|
31
|
+
await Promise.all([...jobs.map((job) => job.retire?.()), ...pendingUtilityRetires]); // 全部 best-effort catch
|
|
32
|
+
// 2. release 全部
|
|
33
|
+
};
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
复用 stopAction 的骨架但**不生成工具结果文案**(不是用户显式 stop,静默级联)。vexillatio 的 pendingUtilityRetires 一并级联。
|
|
37
|
+
|
|
38
|
+
### C. wait/collect 中断路径统一接线
|
|
39
|
+
|
|
40
|
+
所有「signal aborted → return interrupted」的分支(index.ts waitAction 间接层 + runtime.waitOne + collectChild + collectInline + launchFamily abandoned 路径)在返回前触发 cascade(一次性,防重入——用 module-level `cascading` promise 去重即可,同一 signal 只触发一次)。
|
|
41
|
+
|
|
42
|
+
**防重入**:同一 abort 事件可能同时命中多个 in-flight 工具调用(parallel tool calls),cascade 必须幂等:用 `let cascadePromise: Promise<void> | undefined` 缓存,已存在则复用。turn_start 时重置(新 turn 新级联)。
|
|
43
|
+
|
|
44
|
+
### D. vexillatio collect 接 signal
|
|
45
|
+
|
|
46
|
+
`index.ts` launchUtilityFamily(约 :1895):
|
|
47
|
+
```ts
|
|
48
|
+
const result = await handle.orchestrator.collect(handle.name, { timeoutMs, ...(signal ? { signal } : {}) });
|
|
49
|
+
```
|
|
50
|
+
vexillatio 工具 execute 也要把 signal 传进来(找到它的 registerTool 调用,第 3 参数接上)。ESC 后 utility children 也应被 retire(它们进了 pendingUtilityRetires,cascade 覆盖)。
|
|
51
|
+
|
|
52
|
+
### E. 契约/文档更新
|
|
53
|
+
|
|
54
|
+
- docs/contracts/esc-abort-v1.md:顶部加「v2 修订:ESC 语义改为级联关闭,推翻 v1 的『ESC ≠ 杀 children』」——保留原文供考古,加修订记录。
|
|
55
|
+
- docs/design.md、README.md、playbook(TOOL_DESCRIPTION / PARENT_PLAYBOOK)相应语句更新:ESC abort 会级联 retire children;wait 被打断时 children 一并关闭。
|
|
56
|
+
|
|
57
|
+
## 语义边界(不变)
|
|
58
|
+
|
|
59
|
+
- **stop action 不变**:显式停止仍走全链。
|
|
60
|
+
- **主 pi 正常退出(quit)不变**:交互 TUI 的 session_shutdown 仍立即级联 retire。
|
|
61
|
+
- **非交互 print/JSON(#72)**:`ctx.mode` 为 `print` 或 `json` 时,session_shutdown 先等仍活着的 async 子 agent 结算(上限为各子的 turn timeout),再 retire 尚未结束的。避免 `--print` 在首包前把刚 spawn 的子进程记成 `no assistant message for the last prompt`。父会话关机导致的无 assistant abort 原因改为 parent session shutdown,与模型自己没写出 assistant 区分。
|
|
62
|
+
- **SIGKILL/崩溃不覆盖**:孤儿扫描 + resume 语义不变(这是既定接受的风险)。
|
|
63
|
+
- **children 的 children**:retire 链本身递归(孙进程 sweep 在 rpc-supervisor 的 retireChild 里),无需额外处理。
|
|
64
|
+
- **blocked children**:一并 retire(stop 语义一致)。
|
|
65
|
+
|
|
66
|
+
## 文件归属
|
|
67
|
+
|
|
68
|
+
| 文件 | 改动 |
|
|
69
|
+
|---|---|
|
|
70
|
+
| index.ts | cascadeRetireAll + 各中断分支接线 + vexillatio signal |
|
|
71
|
+
| src/extension/playbook.ts | TOOL_DESCRIPTION / PARENT_PLAYBOOK 更新 |
|
|
72
|
+
| docs/contracts/esc-abort-v1.md | v2 修订记录 |
|
|
73
|
+
| docs/design.md, README.md | 语义说明 |
|
|
74
|
+
| test/unit/* | 新测试 |
|
|
75
|
+
|
|
76
|
+
## v2.1 修订(2026-10-13,会话 01a13345 实测后补)
|
|
77
|
+
|
|
78
|
+
v2 的触发点只覆盖了「abort 落在 in-flight subagent 工具调用上」(wait/collect/launch 中途)。**async launch(默认形态)在 ESC 前就早已返回**:ESC 落在模型生成、空档或别的工具上时,没有任何 subagent 工具在执行,signal 无处投递,级联不触发——子 agent 继续跑,直到 session_shutdown 或显式 stop。
|
|
79
|
+
|
|
80
|
+
实测:2026-10-13 03:20Z 会话 01a13345 async 启动 centurion(worktree),03:20:10 ESC abort 父 turn,子 agent 存活至用户退出父会话(03:20:24,走的是 session_shutdown 级联)。
|
|
81
|
+
|
|
82
|
+
**修复**:`index.ts` 注册 `pi.on("agent_settled")`——pi 核心在每个 agent run 结算时发 `{ aborted: boolean }`,ESC abort 后必为 true(见 pi AgentSettledEvent:"Whether the run ended because it was aborted, for example with Escape.")。handler 在 `event.aborted` 时 fire-and-forget `cascadeRetireAll()`(不 await:优雅 retire 可达秒级,不能拖住 settle 路径)。注册点与 turn_start 相邻、位于子进程 early-return 之前,父会话/嵌套子/工具人全部生效;无 runtime 的会话上是 no-op。幂等性由既有 cascadePromise/cascadingJobs 保证:ESC 打断 in-flight 工具时工具路径先触发一次,agent_settled 再触发一次为 no-op。
|
|
83
|
+
|
|
84
|
+
## 验收
|
|
85
|
+
|
|
86
|
+
1. typecheck + unit + integration 全绿。
|
|
87
|
+
2. 新测试:wait 中途 abort → children 被 retire(mock 验证 retire 调用 + cancelWatch + release)。
|
|
88
|
+
3. 新测试:cascade 幂等(同 signal 两次触发只 retire 一次)。
|
|
89
|
+
4. 新测试:parallel 工具调用同时 abort,cascade 只跑一次。
|
|
90
|
+
5. 新测试:vexillatio collect 在 abort 时提前返回(不长等 600s)。
|
|
91
|
+
6. 新测试(v2.1):async launch 已返回后 emitSettled(true) → 子 agent 被 retire、无完成通知。
|
|
92
|
+
7. 新测试(v2.1):emitSettled(false)(正常结算)→ 不 retire,async 子继续运行。
|
|
93
|
+
|
|
94
|
+
## 锚点(以 master bc9c205 为准)
|
|
95
|
+
|
|
96
|
+
- index.ts:687-691(execute 入口 aborted 快速返回)
|
|
97
|
+
- index.ts:832-840(session_shutdown 参考——cascade 参考其形状)
|
|
98
|
+
- index.ts:2243-2280(stopAction 骨架——cascade 复用)
|
|
99
|
+
- index.ts:1890-1900(vexillatio collect)
|
|
100
|
+
- runtime.ts:481-590(waitOne interrupted 分支)
|
|
101
|
+
- master 上无 worktree 依赖,直接在主 repo 改。
|
package/docs/design.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# pi-legion 设计文档
|
|
2
2
|
|
|
3
|
+
> **⚠️ 历史实验笔记(非现行契约)**
|
|
4
|
+
> 本文记录 herdr / pane 时代的实测与设计推演。**运行时契约以 [README](../README.md) 与 [CONTRIBUTING](../CONTRIBUTING.md) 为准**(Pi Legion 2.x = headless Pi RPC + `legion.db`;herdr pane 执行已归档到 `src/backends/legacy/`)。
|
|
5
|
+
> 下文 F 条中标 **✅ landed** 的是已在当前 master 落地的修复;未标注的早期结论仍有参考价值,但不要当作「今日仍坏」的缺口清单。
|
|
6
|
+
|
|
3
7
|
> 基于 10 组实测实验(exp1–exp10)得出的设计。所有结论都标注了实验依据,
|
|
4
8
|
> 未经验证的假设明确标记为「待验证」。
|
|
5
9
|
|
|
@@ -20,7 +24,7 @@
|
|
|
20
24
|
|
|
21
25
|
### 实现状态(相对本文档)
|
|
22
26
|
|
|
23
|
-
下面 F
|
|
27
|
+
下面 F 条目里不少写的是「当时的缺口」(文首 banner 已说明:契约以 README + CONTRIBUTING 为准)。当前运行时已经钉死:
|
|
24
28
|
|
|
25
29
|
- 子进程强制加载 child-guard:拦 `herdr agent prompt|wait|send-keys|start`、外 pane read、只读角色写操作
|
|
26
30
|
- 任务卡自动附录(禁止 wakeup、必须 `{"ok":…}`)
|
|
@@ -584,7 +588,7 @@ preset 规则:
|
|
|
584
588
|
(`src/agents/step-model.ts`),只在该步骤确实引用了 preset 时生效
|
|
585
589
|
- **响亮失败**:引用了未定义的 preset 是错误(列出已定义的 preset),绝不静默
|
|
586
590
|
回退到父会话模型。报错会指明 model 的真实来源,不把责任误归于 preset
|
|
587
|
-
- preset 刻意高于 agentOverrides
|
|
591
|
+
- preset 刻意高于 agentOverrides:通过 `agentOverrides` 钉死的角色模型(`loadCatalog`
|
|
588
592
|
会先把它们折进 `agent.model`),若 preset 放在 frontmatter 同级则对它不可达。
|
|
589
593
|
未引用 preset 的 agent 行为不变
|
|
590
594
|
- 解析逻辑抽到 `src/agents/step-model.ts`(纯函数,便于单测)
|
|
@@ -636,41 +640,38 @@ Team selection is resolved as `PI_SUBAGENTS_TEAM` > `subagents.team` >
|
|
|
636
640
|
string/object members, with `*` expanding all roles once and later object
|
|
637
641
|
members applying the normal agent-override fields. Project team entries replace
|
|
638
642
|
same-named user entries. Non-default team names are passed to child pane/tab
|
|
639
|
-
processes as `PI_SUBAGENTS_TEAM`; `/
|
|
643
|
+
processes as `PI_SUBAGENTS_TEAM`; `/legion team` manages project or user
|
|
640
644
|
settings.
|
|
641
645
|
|
|
642
646
|
### 6.4 总开关 `subagents.enabled`
|
|
643
647
|
|
|
644
|
-
解析顺序:会话内覆盖(`/
|
|
648
|
+
解析顺序:会话内覆盖(`/legion on|off`,仅内存,`/reload` 后回落) >
|
|
645
649
|
项目 `.pi/settings.json` > 用户 `~/.pi/agent/settings.json` > 默认 `true`。
|
|
650
|
+
旧 toggle 的 `flip` 与无参数 `show` 用法已由显式 `/legion on` 或
|
|
651
|
+
`/legion off` 取代;每次执行后都会显示最终状态。
|
|
646
652
|
|
|
647
|
-
关闭后:launch 拒绝(`DISABLED` 错误码,指向 `/
|
|
653
|
+
关闭后:launch 拒绝(`DISABLED` 错误码,指向 `/legion on`);
|
|
648
654
|
system prompt 不再注入 playbook/roster;bash 派发 guard 放行手动 herdr
|
|
649
655
|
命令。已有 children 不受影响——正常完成并通知,`status`/`collect`/
|
|
650
656
|
`wait`/`resume`/`steer` 继续可用。
|
|
651
657
|
|
|
652
|
-
### 6.4
|
|
653
|
-
|
|
654
|
-
角色不写死供应商模型。按 **cheap / medium / strong** 三档绑定:
|
|
655
|
-
|
|
656
|
-
| 档 | 角色 |
|
|
657
|
-
| --- | --- |
|
|
658
|
-
| cheap | scout, prototype |
|
|
659
|
-
| medium | planner |
|
|
660
|
-
| strong | worker, reviewer, designer |
|
|
661
|
-
|
|
662
|
-
(advisor 为 cursor kind 自带模型,不参与 pi 档位。)
|
|
658
|
+
### 6.4.1 Scout guard `subagents.scoutGuard`
|
|
663
659
|
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
660
|
+
只在主会话生效(子进程带 `PI_SUBAGENT_ROLE`,不计数、不注入)。连续 N 次
|
|
661
|
+
读类工具调用(first-class `read`/`grep`/`find`/`ls`,以及可判定为只读的 bash:
|
|
662
|
+
`cat`/`head`/`tail`/`less`/`rg`/`grep`/`find`/`ls`/`stat`/`wc`/`file`/`jq`、
|
|
663
|
+
`git show|log|diff|status|blame`、不带 `-i` 的 `sed`)且中间没有成功的
|
|
664
|
+
`subagent` / `vexillatio` 派发时,异步注入一条 follow-up 提醒,不挡住当前
|
|
665
|
+
`tool_call`。
|
|
668
666
|
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
667
|
+
```json
|
|
668
|
+
{ "subagents": { "scoutGuard": { "enabled": true, "threshold": 8, "cooldownMs": 120000 } } }
|
|
669
|
+
```
|
|
672
670
|
|
|
673
|
-
|
|
671
|
+
默认开启,`threshold` 8,`cooldownMs` 120000。提醒发出后计数清零并进入冷却;
|
|
672
|
+
冷却期内不计数、不重复提醒。成功派发立即清零并退出冷却。`edit`/`write` 和
|
|
673
|
+
写类 bash(含 `sed -i`、写重定向)清零但不进入冷却。无法判定的 bash 不计数
|
|
674
|
+
也不清零。`/scout-guard` 开启、`/no-scout-guard` 关闭,只覆盖本会话。
|
|
674
675
|
|
|
675
676
|
## 7. 借鉴 pi-subagents:三类处理
|
|
676
677
|
|
|
@@ -893,13 +894,16 @@ function countToolErrors(turn: Turn): number {
|
|
|
893
894
|
```ts
|
|
894
895
|
subagent({
|
|
895
896
|
action?: "launch" | "continue" | "steer" | "resume" | "retire"
|
|
896
|
-
| "status" | "collect" | "list",
|
|
897
|
+
| "status" | "collect" | "wait" | "list" | "stop", // 默认 launch
|
|
897
898
|
|
|
898
899
|
// launch
|
|
899
900
|
agent?: string, task?: string,
|
|
900
901
|
tasks?: Array<{ agent: string; task: string }>, // 并行
|
|
901
902
|
async?: boolean, // 默认 true
|
|
902
903
|
model?: string, cwd?: string, placement?: string,
|
|
904
|
+
worktree?: boolean, // 隔离 git worktree(默认随角色)
|
|
905
|
+
verify?: string[], // 收集时由扩展在子 worktree 里机械执行的验证命令;
|
|
906
|
+
// 首个非零退出即 reject。子 agent 无需粘贴测试输出。
|
|
903
907
|
|
|
904
908
|
// 续跑 / 控制
|
|
905
909
|
name?: string, // handle 名,如 "reviewer-1"
|
|
@@ -907,6 +911,18 @@ subagent({
|
|
|
907
911
|
})
|
|
908
912
|
```
|
|
909
913
|
|
|
914
|
+
#### `verify` 的信任链
|
|
915
|
+
|
|
916
|
+
- launch 时 `verify` 合成一条带 `command` 的 acceptance criterion(`task-verify`),快照进子记录的 `pendingCriteria`;
|
|
917
|
+
- collect 时 `applyVerification` 在子 worktree cwd 亲自执行(bash -lc,超时 SIGKILL);
|
|
918
|
+
- 全零退出 → `accepted (verified)`;首个非零 → `rejected`,reason 指名失败的命令;
|
|
919
|
+
- 未提供 `verify` 时扩展**绝不猜命令**,保持 attested 语义不变(F44 边界)。
|
|
920
|
+
|
|
921
|
+
配套设置(`~/.pi/agent/settings.json` → `subagents.legion`):
|
|
922
|
+
|
|
923
|
+
- `worktreeBootstrap`: 新建子 worktree 后自动准备依赖环境。`"npm-install"`(按 lockfile 选 pnpm/bun/yarn/npm)或任意 shell 命令(如 `"ln -sfn /path/to/node_modules ./node_modules"`)。幂等:`.pi-provisioned` 标记文件记录已应用的 mode,同 mode 重入直接跳过(resume 不重装);mode 变更视为声明变更,重新执行。
|
|
924
|
+
- `worktreeBootstrapTimeoutMs`: bootstrap 命令预算,默认 600s。失败即失败整个 launch,worktree 走既有回滚被整体移除。
|
|
925
|
+
|
|
910
926
|
### 动作语义
|
|
911
927
|
|
|
912
928
|
| action | 用途 | 底层 |
|
|
@@ -916,7 +932,15 @@ subagent({
|
|
|
916
932
|
| `steer` | **运行中插话改方向**(F10) | `agent prompt`(不等) |
|
|
917
933
|
| `resume` | **已退出后恢复**(F12) | 新 pane + `--session <file>` |
|
|
918
934
|
| `retire` | 回收 | ctrl+d / pane close / tab close |
|
|
919
|
-
| `status` / `collect` / `list` | 查询 |
|
|
935
|
+
| `status` / `collect` / `list` | 查询 | child record / session JSONL |
|
|
936
|
+
| `wait` | 等待指定或全部活动 child 完成;由 RPC settle 事件唤醒;ESC 中断时级联优雅关闭 children 后返回 | session runtime + RPC supervisor |
|
|
937
|
+
| `stop` | 优雅停止指定或全部 tracked、非 retired children | `retire` 全链 + runtime release |
|
|
938
|
+
|
|
939
|
+
### ESC abort 语义 + stop
|
|
940
|
+
|
|
941
|
+
父 turn 的 ESC / RPC abort signal 会立即打断当前工具等待,并静默级联优雅关闭该 session 所拥有的 tracked children(包括 vexillatio utility children)。`wait` 返回 `interrupted (parent turn aborted)` 前先完成级联 retire;`collect` / inline collect 被中断时也会级联关闭 children,不生成显式 stop 的工具结果文案。级联先取消 completion watch,再并行 retire 并释放 runtime tracking;并发 abort 复用同一级联 promise。新的 turn 会建立新的级联周期。正常完成的 `wait` 仍由 RPC settle 事件立即解除,不需要等满 timeout。
|
|
942
|
+
|
|
943
|
+
`stop` 是显式停止操作:`subagent({ action: "stop", name: "worker-0" })` 停一个 child,`subagent({ action: "stop", all: true })` 逐个停止当前跟踪的全部非 retired children。它复用 `retire` 生命周期(优雅关闭、超时后升级信号、后代清理)并释放 runtime 跟踪;`stop` 本身不接父 turn abort signal。`name` 与 `all` 互斥且必须指定其一。
|
|
920
944
|
|
|
921
945
|
### `continue` vs `steer` vs `resume`
|
|
922
946
|
|
|
@@ -1113,12 +1137,24 @@ index.ts(132,4): error TS7006: Parameter 'signal' implicitly has an 'any' type.
|
|
|
1113
1137
|
|
|
1114
1138
|
---
|
|
1115
1139
|
|
|
1116
|
-
## 16. 交付前安全/健壮性审计(F38–
|
|
1140
|
+
## 16. 交付前安全/健壮性审计(F38–F46)— Historical findings(✅ landed)
|
|
1117
1141
|
|
|
1118
1142
|
对全部模块做了对抗式输入扫描(畸形会话文件、路径穿越、恶意配置、并发写)。
|
|
1119
|
-
|
|
1143
|
+
以下条目**当时**是真缺陷;对照当前 master 均已落地(见各条 ✅),勿再当 open gap。
|
|
1120
1144
|
|
|
1121
|
-
|
|
1145
|
+
| # | 当时缺口 | master 落点(摘要) |
|
|
1146
|
+
| --- | --- | --- |
|
|
1147
|
+
| F38 | glob→RegExp ReDoS | `matchesScopePattern` 双指针 glob,**不用 RegExp** |
|
|
1148
|
+
| F39 | `openSync`/`closeSync` fd 泄漏 | session 预创建改 `writeFileSync(..., { flag: "wx" })` |
|
|
1149
|
+
| F40 | `JSON.parse` 标量拖垮会话解析 | `decodeEvent` 非对象计入 `tornLines` |
|
|
1150
|
+
| F41 | `tasks[]` 条目未校验 | `firstInvalidStep` / 启动前校验 agent+task |
|
|
1151
|
+
| F42 | 空白 `task` 被 `Boolean` 放行 | 存在性按 `trim()` |
|
|
1152
|
+
| F43 | 角色 `timeoutMs` 被忽略 | launch 记入 `timeoutByName`,follow/wait 使用 |
|
|
1153
|
+
| F44 | `acceptance.criteria` 静默丢弃 | `pendingCriteria` + command 才升 `verified` |
|
|
1154
|
+
| F45 | 未生效配置看起来生效 | `UNENFORCED_FIELDS` 现为空;list 不再假警告 |
|
|
1155
|
+
| F46 | 嵌套 YAML acceptance 未解析 | `parseAcceptance` + `parseIndentedBlock` |
|
|
1156
|
+
|
|
1157
|
+
### F38 — ✅ landed — ReDoS:glob → RegExp 的嵌套量词(安全)
|
|
1122
1158
|
|
|
1123
1159
|
`modelScope.allow` 的 glob 被翻译成 `.*`,于是 `*a*a*a…b` 变成 `.*a.*a.*a…b`——
|
|
1124
1160
|
嵌套量词在**不匹配**的输入上指数回溯。
|
|
@@ -1133,7 +1169,7 @@ index.ts(132,4): error TS7006: Parameter 'signal' implicitly has an 'any' type.
|
|
|
1133
1169
|
**修法**:不用正则,改用双指针贪心 glob 匹配(只回溯最近一个 `*`)。
|
|
1134
1170
|
修复后 n=6400 仅 2ms。
|
|
1135
1171
|
|
|
1136
|
-
### F39 — fd 泄漏:`openSync`/`closeSync` 无保护
|
|
1172
|
+
### F39 — ✅ landed — fd 泄漏:`openSync`/`closeSync` 无保护
|
|
1137
1173
|
|
|
1138
1174
|
```ts
|
|
1139
1175
|
const fd = fs.openSync(file, "w", 0o600);
|
|
@@ -1146,7 +1182,7 @@ launcher 为**每个 child** 创建一个 session 文件,所以泄漏会随 fa
|
|
|
1146
1182
|
**修法**:`fs.writeFileSync(file, "", { flag: "wx", mode: 0o600 })`——
|
|
1147
1183
|
由 Node 自己管理描述符,并且 `wx` 顺带消除了 `existsSync` 检查留下的 TOCTOU 窗口。
|
|
1148
1184
|
|
|
1149
|
-
### F40 — `JSON.parse("null")` 拖垮整个会话解析
|
|
1185
|
+
### F40 — ✅ landed — `JSON.parse("null")` 拖垮整个会话解析
|
|
1150
1186
|
|
|
1151
1187
|
`JSON.parse` 对标量是成功的:`null` / `42` / `true` / `"x"`。
|
|
1152
1188
|
随后 `event.type` 在 `null` 上抛异常,**整个 `parseSessionText` 崩溃**,
|
|
@@ -1154,7 +1190,7 @@ launcher 为**每个 child** 创建一个 session 文件,所以泄漏会随 fa
|
|
|
1154
1190
|
|
|
1155
1191
|
**修法**:非对象、非数组的标量按损坏行计入 `tornLines`,继续解析其余行。
|
|
1156
1192
|
|
|
1157
|
-
### F41 — `tasks[]` 的条目未校验
|
|
1193
|
+
### F41 — ✅ landed — `tasks[]` 的条目未校验
|
|
1158
1194
|
|
|
1159
1195
|
单任务路径用 `Boolean(params.agent && params.task)` 把关,但数组路径直接放行:
|
|
1160
1196
|
|
|
@@ -1165,12 +1201,12 @@ tasks:[{task:"do it"}] → 放行,agent 名为 undefined
|
|
|
1165
1201
|
|
|
1166
1202
|
**修法**:每个 step 在分配任何资源之前校验 `agent` 与 `task`。
|
|
1167
1203
|
|
|
1168
|
-
### F42 — `Boolean(" ")` 为真:纯空白 task 被放行
|
|
1204
|
+
### F42 — ✅ landed — `Boolean(" ")` 为真:纯空白 task 被放行
|
|
1169
1205
|
|
|
1170
1206
|
即使单任务路径,`task: " "` 也会通过,生成一个毫无意义的 `Task:` prompt。
|
|
1171
1207
|
**修法**:存在性按 `trim()` 后的内容判定,而非 `Boolean()`。
|
|
1172
1208
|
|
|
1173
|
-
### F43 — `timeoutMs` 被解析却从不生效
|
|
1209
|
+
### F43 — ✅ landed — `timeoutMs` 被解析却从不生效
|
|
1174
1210
|
|
|
1175
1211
|
5 个自带角色都声明了预算,运行时却全部忽略,永远用全局默认 15 分钟:
|
|
1176
1212
|
|
|
@@ -1182,7 +1218,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
|
|
|
1182
1218
|
|
|
1183
1219
|
**修法**:`collect` 采用 `agent.timeoutMs`(按 child 记录,逐个子 agent 生效)。
|
|
1184
1220
|
|
|
1185
|
-
### F44 — `acceptance.criteria` 被静默丢弃
|
|
1221
|
+
### F44 — ✅ landed — `acceptance.criteria` 被静默丢弃
|
|
1186
1222
|
|
|
1187
1223
|
角色可以声明 `must: "测试通过"` 这类**语义**验收条件,代码解析后就不管了。
|
|
1188
1224
|
调用方无法知道「没有任何东西验证过它」。
|
|
@@ -1193,7 +1229,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
|
|
|
1193
1229
|
**修法**:criteria 作为**待验证清单**回传调用方(`pendingCriteria`),
|
|
1194
1230
|
且 `level` 保持 `attested`——**`verified` 只留给真正被人核对过的证据**。
|
|
1195
1231
|
|
|
1196
|
-
### F45 — 配置字段「看起来生效、实际无效」
|
|
1232
|
+
### F45 — ✅ landed — 配置字段「看起来生效、实际无效」
|
|
1197
1233
|
|
|
1198
1234
|
自带角色携带 `onBlocked` / `allowNestedSubagents` / `fallbackModels` / `toolTimeoutMs`,
|
|
1199
1235
|
全部被解析、全部不生效。其中 `allowNestedSubagents: false` 最危险——
|
|
@@ -1208,7 +1244,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
|
|
|
1208
1244
|
**原则**:**一个被接受却不做事的键,比一个未知的键更危险**——
|
|
1209
1245
|
用户会相信它已经在保护自己。
|
|
1210
1246
|
|
|
1211
|
-
### F46 — 嵌套 YAML 块从未被解析:自带角色的 acceptance 全部丢失
|
|
1247
|
+
### F46 — ✅ landed — 嵌套 YAML 块从未被解析:自带角色的 acceptance 全部丢失
|
|
1212
1248
|
|
|
1213
1249
|
frontmatter 解析器是**扁平的**(只处理 `key: value`);一个嵌套块会以
|
|
1214
1250
|
**剥掉公共缩进后的原始文本**返回:
|