pi-legion 3.1.0 → 5.0.0
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 +382 -2
- package/CONTRIBUTING.md +4 -17
- package/README.md +127 -66
- package/agents/centurion.md +20 -16
- package/agents/scout.md +3 -1
- package/agents/worker.md +6 -8
- package/docs/contracts/declarative-phase-machine-v5.md +128 -0
- package/docs/contracts/display-liveness-v1.md +373 -0
- package/docs/contracts/drop-non-pi-kinds-v4.md +198 -0
- package/docs/contracts/esc-abort-v1.md +4 -4
- package/docs/contracts/esc-no-retire-v3.md +2 -2
- package/docs/contracts/launch-admission-queue-v1.md +839 -0
- package/docs/contracts/status-panel-v1.md +174 -0
- package/docs/contracts/subagent-renewal-v1.md +260 -0
- package/docs/headless-child-contract.md +6 -3
- package/docs/inprocess-supervisor.md +106 -27
- package/docs/legion-v2-contract.md +27 -2
- package/docs/performance-2026-10-19.md +199 -0
- package/docs/spawn-mode-visibility-v1.md +4 -1
- package/docs/vexillatio-contract.md +3 -1
- package/index.ts +1155 -120
- package/package.json +5 -3
- package/skills/pi-legion/SKILL.md +2 -3
- package/src/agents/agents.ts +310 -46
- package/src/agents/overrides.ts +3 -2
- package/src/agents/presets.ts +14 -40
- package/src/agents/settings.ts +32 -95
- package/src/agents/step-model.ts +7 -22
- package/src/api.ts +1 -35
- package/src/extension/child-guard.ts +25 -1
- package/src/extension/event-bus.ts +80 -8
- package/src/extension/legion-commands.ts +41 -17
- package/src/extension/legion-doctor.ts +1 -1
- package/src/extension/legion-stop.ts +39 -13
- package/src/extension/legion-tools.ts +87 -25
- package/src/extension/liveness.ts +200 -0
- package/src/extension/notify.ts +136 -4
- package/src/extension/playbook.ts +4 -4
- package/src/extension/recycle.ts +4 -0
- package/src/extension/runtime.ts +435 -16
- package/src/extension/slash.ts +0 -21
- package/src/extension/summary.ts +14 -5
- package/src/extension/timing.ts +8 -4
- package/src/legion/db.ts +165 -1
- package/src/legion/events.ts +81 -16
- package/src/legion/nodes.ts +13 -2
- package/src/legion/phase-conditions.ts +164 -0
- package/src/legion/phase-machine.ts +403 -0
- package/src/legion/rebuild.ts +7 -1
- package/src/legion/state-machine.ts +219 -115
- package/src/legion/usage.ts +58 -4
- package/src/runs/args.ts +32 -18
- package/src/runs/extension-inheritance.ts +220 -0
- package/src/runs/orchestrator.ts +1292 -96
- package/src/runs/progress-signal.ts +137 -0
- package/src/runs/store-lookup.ts +270 -0
- package/src/runs/worktree.ts +190 -21
- package/src/shared/ignored-kind.ts +57 -0
- package/src/shared/progress.ts +11 -0
- package/src/shared/session.ts +199 -19
- package/src/shared/types.ts +138 -69
- package/src/supervisor/admission-queue.ts +516 -0
- package/src/supervisor/child-context.ts +19 -0
- package/src/supervisor/inprocess-supervisor.ts +137 -38
- package/src/supervisor/proc-memory.ts +67 -0
- package/src/supervisor/routing-supervisor.ts +60 -2
- package/src/supervisor/rpc-supervisor.ts +2 -2
- package/src/tui/session-messages-file.ts +100 -0
- package/src/tui/status.ts +91 -18
- package/src/tui/tree-view.ts +84 -3
- package/src/tui/viz/layout.ts +54 -3
- package/src/tui/viz/model.ts +67 -14
- package/src/tui/viz/palette.ts +11 -3
- package/src/tui/viz/panels.ts +222 -8
- package/src/tui/viz/view.ts +110 -23
- package/agents/advisor.md +0 -110
- package/agents/designer.md +0 -87
- package/agents/planner.md +0 -53
- package/agents/prototype.md +0 -72
- package/agents/reviewer.md +0 -113
- package/src/backends/legacy/client.ts +0 -638
- package/src/backends/legacy/cursor-chat.ts +0 -348
- package/src/backends/legacy/runner.ts +0 -101
- package/src/backends/legacy/types.ts +0 -138
- package/src/runs/kind.ts +0 -260
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Status panel v1 — `/legion` 大盘的 status 面板 + status 字段缺口补齐
|
|
2
|
+
|
|
3
|
+
> 冻结契约。合并权人裁定,worker 不得自行解释矛盾,遇矛盾向父会话报告。
|
|
4
|
+
> 基线:`3071dee` (3.1.0),`npm run typecheck` = 0、`npm test` = 0。
|
|
5
|
+
|
|
6
|
+
## 0. 目标
|
|
7
|
+
|
|
8
|
+
1. 在 `/legion` 全屏大盘(`src/tui/viz/`)新增 `status` 面板,把目前只存在于聊天文本里的 `/legion status` 数据搬到大盘上。
|
|
9
|
+
2. 补齐 `/legion status` 的已知缺口:`supervisor=unknown`、`owner` 缺失、无内存、无 context tokens、`usage` 未格式化。
|
|
10
|
+
|
|
11
|
+
## 1. 不可违反的既有约束
|
|
12
|
+
|
|
13
|
+
| 约束 | 锚点 |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| **禁止给 `legion.db` 加列、禁止升 `LEGION_DB_USER_VERSION`** | `docs/spawn-mode-visibility-v1.md:143`、`test/unit/legion-schema-sentinel.test.ts` |
|
|
16
|
+
| 运行时零外部依赖(Node stdlib only) | `CONTRIBUTING.md:215` |
|
|
17
|
+
| 每行 `visibleWidth === w`(严格相等,非 ≤) | `test/unit/legion-viz.test.ts:417-434,628,911,1464,1630` |
|
|
18
|
+
| 平台降级不得抛错:非 Linux 返回空值 | 先例 `src/supervisor/proc-tree.ts:44` |
|
|
19
|
+
| `spawnMode` 缺失必须渲染 `unknown`,**绝不猜 `rpc`** | `src/extension/runtime.ts:84-89`、`test/unit/runtime.test.ts:1490-1501` |
|
|
20
|
+
|
|
21
|
+
## 2. 设计决策
|
|
22
|
+
|
|
23
|
+
### D1 — 新增第 5 个 pane,但 portrait 不渲染
|
|
24
|
+
|
|
25
|
+
- `wide` / `stacked` 新增 `status` rect;`portrait` 的 `layout.status` 返回**零面积 rect** `{x,y,w:0,h:0}`。
|
|
26
|
+
- 理由:portrait `46×24` 实测 `galaxy=5 chart=10 timing=3 log=3`,`bodyH=21`,4 个 pane 最小高之和 `3+10+3+3=19`,仅剩 2 行 —— 物理上装不下第 5 个 pane(最小 3 行)。`timing`/`log` 在 `h=3` 时内框 `h=1`,`drawTiming`/`drawLog` 本就提前 return,**portrait 极矮时这两个 pane 已是空壳**。
|
|
27
|
+
- `frame()` 在 `h<3` 已早退且不画任何东西,所以零面积 rect 天然安全,无需特判绘制。
|
|
28
|
+
- **Tab 必须跳过零面积 pane**:新增 `availablePanes(layout)`,返回 `h>0` 的 pane 列表;`handleViewKey` 增加可选第 4 参 `panes`,**缺省 = 全部 pane**(保证既有测试不变)。
|
|
29
|
+
- 被否决:(a) 全布局都加 → portrait 溢出 footer;(b) status 复用 timing 做可切换视图 → 隐藏态发现性差,且 `drawTiming` 宽度算术已很紧;(c) 把 status 塞进 log → 语义冲突。
|
|
30
|
+
|
|
31
|
+
### D2 — inprocess 内存口径:只显示 host rss,禁止按子 agent 摊派
|
|
32
|
+
|
|
33
|
+
- `rpc` 子 agent:有独立 pid → 显示 per-child `rss`。
|
|
34
|
+
- `inprocess` 子 agent:**没有独立进程**(`inprocess-supervisor.ts:751-754` 只返回 name+sessionFile)。面板与 status 文本中 **inprocess 行的 rss 列留空/`—`**,另起一行显示 `host rss <N> MB · shared by N inprocess`。
|
|
35
|
+
- **严禁**按 token 比例把 host rss 摊到子 agent 头上 —— 那是编造数据,用户会拿它做决策。
|
|
36
|
+
- 理由:诚实性优先于信息密度。
|
|
37
|
+
|
|
38
|
+
### D3 — pid 穿透(不加 DB 列)
|
|
39
|
+
|
|
40
|
+
链路:`ChildHandle.pid` → `Handle.pid` → `TrackedJobInput.pid` → `StatusEntry.pid` → `VizNode.pid`。
|
|
41
|
+
|
|
42
|
+
- `src/shared/types.ts:482` `Handle` **当前无 pid**,必须加 `pid?: number`。
|
|
43
|
+
- `src/runs/orchestrator.ts:800` 附近(`spawnMode: mode` 同处)写入 `...(result.pid ? { pid: result.pid } : {})`。
|
|
44
|
+
- `TrackedJobInput`(`src/extension/runtime.ts:73-107`)加 `pid?: number`;`index.ts:2675` 的 `runtime.track({...})` 补传。
|
|
45
|
+
- pid 不落盘是既有事实,**不新增持久化**——viz 只在当前宿主进程可见,跨进程显示为未知。
|
|
46
|
+
|
|
47
|
+
### D4 — context tokens:扩 `ParsedSession`,不做百分比
|
|
48
|
+
|
|
49
|
+
- `accumulateUsage`(`src/shared/session.ts:124-136`)在累加的同时,把**最后一条 assistant message** 的 `input + cacheRead + cacheWrite` 记到 `ParsedSession.lastContextTokens`。
|
|
50
|
+
- `LiveProgress`(`src/shared/progress.ts:9-28`)加 `contextTokens?: number`;`progressFromSession` 投影;`mergeProgress` 用「later wins」语义。
|
|
51
|
+
- **不显示百分比**:`contextWindow` 在 JSONL 中不存在,全仓零命中。要百分比就得引模型注册表,超出本契约范围。显示绝对值 `ctx 24.3K tok`。
|
|
52
|
+
- 被否决:直读 session JSONL 最后一条 assistant usage → 与既有 `parseSessionFile` 重复解析,且绕过 `accumulateUsage` 单一事实源。
|
|
53
|
+
|
|
54
|
+
### D5 — 修 `childStatus` 漏传(现存 bug)
|
|
55
|
+
|
|
56
|
+
`index.ts:926-946` 的 `childStatus` 回调补 `spawnMode` 与 `owner`:
|
|
57
|
+
|
|
58
|
+
- `spawnMode: child.spawnMode`(run.json 已有值,`src/shared/types.ts:365-373`)
|
|
59
|
+
- `owner:` 用既有 `runOwnerStatus(runDir)`(`src/runs/owner.ts:60` 返回 `live|dead|unknown`)
|
|
60
|
+
- 正确范例:`index.ts:1417-1428`、`index.ts:2887-2899`(这两处**已传** spawnMode)。
|
|
61
|
+
- 这是纯 bug fix,与新增面板解耦,可独立验收。
|
|
62
|
+
|
|
63
|
+
### D6 — 所有新字段一律 optional
|
|
64
|
+
|
|
65
|
+
`VizNode` 新增字段必须 optional,否则 3 处字面量构造编译失败:`test/unit/legion-viz.test.ts:18-20`、`test/unit/legion-stop.test.ts:92`、`src/tui/viz/panels.ts:103-105`。
|
|
66
|
+
|
|
67
|
+
投影沿用仓库惯例 `...(cond ? {k:v} : {})`(`model.ts:72-79`),**不写 `undefined` 字面量**。
|
|
68
|
+
|
|
69
|
+
### D7 — status 面板字段集与宽度降级档位
|
|
70
|
+
|
|
71
|
+
表头 1 行 + 可选页脚 1 行;列按**绝对列数**分层(沿用 `drawTiming` 惯例):
|
|
72
|
+
|
|
73
|
+
| 内框宽 | 列 |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `w >= 72` | `name · role · state · supervisor · ctx · rss · turns` |
|
|
76
|
+
| `w >= 52` | `name · state · supervisor · ctx` |
|
|
77
|
+
| `w >= 36` | `name · state · ctx` |
|
|
78
|
+
| `w >= 20` | `name · state` |
|
|
79
|
+
| `w < 20` | 不画(return) |
|
|
80
|
+
|
|
81
|
+
- 守卫:`if (r.w < 20 || r.h < 2) return;`(`drawTiming` 用 `w<8,h<2`;本面板列多,下限提到 20)
|
|
82
|
+
- `footerH = rows.length > 0 && r.h >= 4 ? 1 : 0`;`rowsAvail = max(0, r.h - 1 - footerH)`
|
|
83
|
+
- **所有 `cv.text` 必须带 `maxX` 或先 `ellipsize`** —— 禁止复制 `drawLog`(`panels.ts:530-532`)的越界 bug。
|
|
84
|
+
- `rss` 列:rpc → `152M`;inprocess → `—`;未知 → `—`。**不得写大写单位**(`legion-viz.test.ts:927` 的字符类只含小写 a-z),用 `M` 会红 → 改用 `m`;或把该断言一并更新(见 §5)。
|
|
85
|
+
|
|
86
|
+
### D8 — Tab 顺序:status 追加到末尾
|
|
87
|
+
|
|
88
|
+
`PANES = ["galaxy","chart","timing","log","status"]`(`src/tui/viz/view.ts:36`)。
|
|
89
|
+
|
|
90
|
+
- 追加在末尾使 `legion-viz.test.ts:442`(chart)、`:444`(timing)、`:446`(log)**全部继续通过**,只需新增一条 status 断言。
|
|
91
|
+
- 被否决:插入 timing 与 log 之间 → 直接打红 3 条既有断言,且 `:1588-1593` 再红一条。
|
|
92
|
+
|
|
93
|
+
## 3. 文件所有权(严格边界,禁止越界)
|
|
94
|
+
|
|
95
|
+
### Worker A — 数据管道 + status 文本(先做)
|
|
96
|
+
|
|
97
|
+
| 文件 | 性质 |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| `src/supervisor/proc-memory.ts` | **新增**:`readProcRss(pid)`,读 `/proc/<pid>/status` 的 `VmRSS`/`VmHWM`,非 Linux / 读失败 / pid 已退 → `undefined`,绝不抛 |
|
|
100
|
+
| `src/shared/types.ts` | 改:`Handle.pid?`、`ParsedSession.lastContextTokens?` |
|
|
101
|
+
| `src/shared/session.ts` | 改:`accumulateUsage` 记录最后一条 assistant 的 context tokens |
|
|
102
|
+
| `src/shared/progress.ts` | 改:`LiveProgress.contextTokens?` + `progressFromSession` + `mergeProgress` |
|
|
103
|
+
| `src/runs/orchestrator.ts` | 改:`Handle` 写入 `pid` |
|
|
104
|
+
| `src/extension/runtime.ts` | 改:`TrackedJobInput.pid?`、`statusEntryFromJob`/`statusEntryFromNode` 写 `spawnMode/pid/contextTokens/rss`、`renderLiveChildStatus` 增 memory/ctx 行 |
|
|
105
|
+
| `src/tui/status.ts` | 改:`StatusEntry` 加 `spawnMode?/pid?/contextTokens?/rss?`(**不动 `formatWidgetLines`**) |
|
|
106
|
+
| `index.ts` | 改:`childStatus` 补 `spawnMode`/`owner`;`runtime.track` 补 `pid` |
|
|
107
|
+
| `test/unit/proc-memory.test.ts` | **新增** |
|
|
108
|
+
| `test/unit/legion-status.test.ts` | 改:新增字段断言(`:110-147`、`:192-254` 现有断言**不得放宽**,只追加) |
|
|
109
|
+
| `test/unit/runtime.test.ts` | 改:`renderLiveChildStatus` 新行断言 |
|
|
110
|
+
|
|
111
|
+
**Worker A 严禁触碰**:`src/tui/viz/**`、`src/tui/tree-view.ts`、`src/tui/live-overlay.ts`、`docs/**`。
|
|
112
|
+
|
|
113
|
+
### Worker B — viz 面板(等 A 合入后)
|
|
114
|
+
|
|
115
|
+
| 文件 | 性质 |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| `src/tui/viz/layout.ts` | 改:`LegionLayout.status: Rect` + 三批分支 + `availablePanes` |
|
|
118
|
+
| `src/tui/viz/panels.ts` | 改:`Pane` 联合加 `"status"`;**新增 `drawStatus`**;**不修改** 既有 4 个 draw* |
|
|
119
|
+
| `src/tui/viz/view.ts` | 改:`PANES` 末尾追加;`frame`+`drawStatus` 调用;`clampList` 支持 `"status"`;`handleViewKey` 第 4 参 `panes` |
|
|
120
|
+
| `src/tui/viz/model.ts` | 改:`VizNode` 加 optional 字段 + `nodesFromEntries` 投影 |
|
|
121
|
+
| `test/unit/legion-viz.test.ts` | 改:新增 status 面板断言(§5 清单) |
|
|
122
|
+
|
|
123
|
+
**Worker B 严禁触碰**:`src/extension/**`、`src/shared/**`、`src/runs/**`、`src/tui/status.ts`、`index.ts`。
|
|
124
|
+
|
|
125
|
+
## 4. 分阶段与验收
|
|
126
|
+
|
|
127
|
+
| 阶段 | 内容 | 验收 |
|
|
128
|
+
| --- | --- | --- |
|
|
129
|
+
| P1 | Worker A 全量 | `npm run typecheck` && `npm test` |
|
|
130
|
+
| P2 | Worker B 全量(依赖 P1 已合入) | `npm run typecheck` && `npm test` |
|
|
131
|
+
|
|
132
|
+
每个阶段必须 **typecheck 0 / test 0**。首个非零退出即判 rejected。
|
|
133
|
+
|
|
134
|
+
## 5. 必须同步更新的测试(逐条)
|
|
135
|
+
|
|
136
|
+
| 测试 | 原因 | 期望 |
|
|
137
|
+
| --- | --- | --- |
|
|
138
|
+
| `legion-viz.test.ts:417-434` | 新增 status 面板标题 | 追加 `plain.some(l => l.includes("status"))`;**不得放宽** `visibleWidth === w` |
|
|
139
|
+
| `legion-viz.test.ts:437-459` | Tab 顺序末尾新增 | 在 `:446` 后追加 `handleViewKey("\t")` → `assert.equal(state.focus, "status")`;既有 3 条保留 |
|
|
140
|
+
| `legion-viz.test.ts:160-183` | layout 新字段 | `for (const r of [galaxy,chart,timing,log,status])` 加入界内断言;**portrait 跳过 status**(零面积) |
|
|
141
|
+
| `legion-viz.test.ts:872-901` | 几何锁 | portrait 段保持四段相接断言不变;wide 段新增「右列三段相接」断言 |
|
|
142
|
+
| `legion-viz.test.ts:927` | header 字符类 | 若 header 未变则不动;**status 面板内容不写入 header** |
|
|
143
|
+
| `legion-viz.test.ts` 新增块 | `drawStatus` 单测 | 覆盖 D7 四档宽度 + `w<20` 退化 + inprocess `rss` 为 `—` |
|
|
144
|
+
| `legion-status.test.ts:110-147` | 新增 memory/ctx 行 | 既有首行/`alive`/`execution snapshot` 断言保留,追加新行断言 |
|
|
145
|
+
| `legion-status.test.ts:192-254` | `formatTree` 未变 | **不动**(`formatTree` 不在本契约改动范围) |
|
|
146
|
+
|
|
147
|
+
## 6. 风险与裁决
|
|
148
|
+
|
|
149
|
+
| 风险 | 裁决 |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `drawLog` 内框 `w<=14` 写出 rect 右边界(`panels.ts:530-532`) | **顺手修**:给该 `cv.text` 补 `maxX: r.x + r.w`。属 P2 范围,单独 commit,附回归断言。理由:Worker B 正在改同一文件,且新面板极易复制此模式。**勘误**:`Canvas.text` 的 `maxX` 是**排他上界**(`canvas.ts:39` `if (col >= limit) break`),而 `frame()` 返回的是内框、其右边框列即 `r.x + r.w`,所以「保住最后一个合法内格且不碰边框」的值是 `r.x + r.w`(与 `frame()` / `drawStatus` 一致)。本文早期写的 `r.x + r.w - 1` 会少吃一格,已按 #251 评审改为 `r.x + r.w`。 |
|
|
152
|
+
| view 层 `layout.timing.h - 3` 与 draw 层 `innerH-1-footerH` off-by-one(`view.ts:90`) | **本契约不修**。改动会影响 `timingVisible` 语义与既有断言,独立提 issue。新面板**必须**用精确公式,不照抄 `-3`。 |
|
|
153
|
+
| portrait 零面积 status 被 Tab 跳过 | 由 `availablePanes` 保证;`handleViewKey` 缺省参数保证既有测试不变 |
|
|
154
|
+
| pid 跨进程不可见 | 接受。viz 显示 `—`,不猜。 |
|
|
155
|
+
| `readProcRss` 的 pid 复用 race | **实现为「不打印」**:`!alive` 时直接不读 `/proc`,返回 `undefined`。v1 无 last-known 缓存设施(`memoryLine` 无状态、`TrackedJob` 无 rss 字段),新增缓存需额外的失效规则,比不打印更易说谎。`(last)` 分支**明确不在 v1 范围**。读取必须 try/catch。 |
|
|
156
|
+
|
|
157
|
+
## 7. 契约修订点
|
|
158
|
+
|
|
159
|
+
- 本文件即新增契约,无需改动 `docs/legion-v2-contract.md` §10.1(三层 UI 定义不变,status 面板属第 2 层内部枚举新增)。
|
|
160
|
+
- `docs/tui-viewer-contract.md:202` 的禁改清单**不包含** `src/tui/viz/**`,Worker B 无需先修订该文档。
|
|
161
|
+
- `README.md` 的「Three-layer visualization」段落可在 P2 后追加一句 status 面板说明(可选,非门禁)。
|
|
162
|
+
|
|
163
|
+
## 8. 契约勘误(P1 实施中记录)
|
|
164
|
+
|
|
165
|
+
1. **§5 必改测试表漏列 `test/unit/progress.test.ts`**。D4 的 `progressFromSession` 投影让该文件两处完整对象 `deepEqual` 机械性必红。实际处理:加 `contextTokens: 10` 两行,属**加强断言**(新字段被钉死),零删除。
|
|
166
|
+
2. **`runtime.test.ts` 既有 D2 测试与 §6 冲突**。该测试原本用 `alive: false` + pid 断言「有 memory 行」,与 pid 复用防护直接矛盾。实际处理:把前置条件改为 `alive: true`,断言文本/正则/非 Linux 分支全部原样保留,强度不变。
|
|
167
|
+
3. **`(last)` 展示未实现**(见 §6 修订)。
|
|
168
|
+
|
|
169
|
+
## 9. 修订历史
|
|
170
|
+
|
|
171
|
+
| 日期 | 版本 | 说明 |
|
|
172
|
+
| --- | --- | --- |
|
|
173
|
+
| 2026-10-19 | v1 | 初版。父会话直接裁定(planner 卡死于「声称写文档但从不落盘」,已止损)。 |
|
|
174
|
+
| 2026-10-19 | v1.1 | P1 交付后补:pid 复用裁决改为「不打印」;记录 3 条勘误。 |
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
# 子 agent 续约契约 v1(FROZEN)
|
|
2
|
+
|
|
3
|
+
> 状态:**FROZEN**(2026-10-24 用户提出"能不能加个续约的能力")。
|
|
4
|
+
> 冲突时**停下报告**,不得重新解释本契约。
|
|
5
|
+
> 关联:#270(本契约跟踪号)。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## §1 问题陈述
|
|
10
|
+
|
|
11
|
+
用户原话:
|
|
12
|
+
|
|
13
|
+
> 能不能加个续约的能力,比如上层 agent 看到超时了,可以看看他实际有没有推进,
|
|
14
|
+
> 如果实际推进了,他可以选择续约,让任务继续,而不是丢弃,
|
|
15
|
+
> 不然 worker 的工作浪费了
|
|
16
|
+
|
|
17
|
+
### 实际发生的事(已确证)
|
|
18
|
+
|
|
19
|
+
一天之内两次:
|
|
20
|
+
|
|
21
|
+
| 事件 | 结果 |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `W2`(`runtime.ts` 的 D3 投影改造) | 30 分钟耗尽,**零产出落盘** |
|
|
24
|
+
| `W4`(TUI 五文件) | 代码写完,卡在验证/报告;**已找到的编译错误被它自己 revert 掉了**(为了守文件归属纪律) |
|
|
25
|
+
|
|
26
|
+
两者都不是"做错了",而是**在正确的路径上被切断**。
|
|
27
|
+
|
|
28
|
+
### 关键事实(侦察确证,带证据)
|
|
29
|
+
|
|
30
|
+
1. **session 文件完整保留。** `.pi-subagents/runs/r-491ceace/worker-3.jsonl`
|
|
31
|
+
有 271 行 / 1.4MB,最后一条是 `thinking` —— 说明它是**在思考或工具执行中途**被切断的。
|
|
32
|
+
2. **续接机制已经存在。** `index.ts:1844-1861` 的 `reviveChild`:
|
|
33
|
+
```ts
|
|
34
|
+
if (supervisor.isAlive(name)) {
|
|
35
|
+
await orchestrator.steer(name, params.message); // 活着:追加消息
|
|
36
|
+
}
|
|
37
|
+
const handle = await orchestrator.launch({ agent, task, name, ... }); // 死了:复用 session
|
|
38
|
+
// → "Context preserved from <sessionFile>"
|
|
39
|
+
```
|
|
40
|
+
3. **两种超时必须区分**(这是 §3 D1 的基础):
|
|
41
|
+
- `wait { timeoutMs }` / `collect { timeoutMs }`(`index.ts:1768`, `:2616`)
|
|
42
|
+
→ **父侧放弃等待,不杀 child**。`inprocess-supervisor.ts:1084` 只 `resolve({settled:false, reason:"timeout"})`。
|
|
43
|
+
- 角色 `timeoutMs`(`agents/worker.md:9` 等)
|
|
44
|
+
→ 由 **pi 宿主**执行,child 被终止。pi-legion 源码里**没有** `terminated` 这个字面量
|
|
45
|
+
(全仓 grep 只命中 `src/shared/session.ts:912` 的 "terminated during tool call" 文案)。
|
|
46
|
+
|
|
47
|
+
**结论:pi-legion 无法阻止宿主终止 child,但能在终止后识别、评估、续约。** 契约按此边界设计。
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## §2 根因(为什么现在做不到)
|
|
52
|
+
|
|
53
|
+
### R1 — 超时终止被当成"失败",没有分类
|
|
54
|
+
|
|
55
|
+
`execution: failed (terminated)` 在展示层与其他失败混在一起。
|
|
56
|
+
父会话看到的是一条"失败通知",没有"这个 child 被超时切断、其 session 可续"的语义。
|
|
57
|
+
|
|
58
|
+
### R2 — 没有"推进度"概念
|
|
59
|
+
|
|
60
|
+
要判断"该不该续约",必须回答"这 30 分钟他是在干活还是卡死"。现有信号分散:
|
|
61
|
+
|
|
62
|
+
| 信号 | 位置 | 能回答 |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| `lastJsonlEventAgeMs` | `runtime.ts` | 最近一次活动距今多久 |
|
|
65
|
+
| `progressFromSessionFile` | `src/shared/progress.ts` | 解析出的进度摘要 |
|
|
66
|
+
| `NodeActivity{turn,tools,turnStartedAt}` | `runtime.ts` | 第几轮、用过什么工具 |
|
|
67
|
+
| `COLLECT_DEADLINE_REASON` | `orchestrator.ts:280` | 父侧放弃等待(≠ child 死) |
|
|
68
|
+
|
|
69
|
+
但**没有任何一个**被用来回答"该不该续约"。
|
|
70
|
+
|
|
71
|
+
### R3 — `wait`/`collect` 超时与 child 终止被混为一谈
|
|
72
|
+
|
|
73
|
+
`inprocess-supervisor.ts:1084` 的超时只表示"我没等到",child 可能还在跑。
|
|
74
|
+
把它当成 child 失败会导致**错误地重派**(浪费)或**错误地放弃**(丢失)。
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## §3 决策
|
|
79
|
+
|
|
80
|
+
### D1 — 只对"真终止 + 有推进"提议续约
|
|
81
|
+
|
|
82
|
+
续约提议的**必要且充分条件**:
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
1. child 确实被终止(不是父侧 wait/collect 超时)
|
|
86
|
+
2. 自上次续约点以来有可观测推进
|
|
87
|
+
3. 该角色允许续约(见 D5)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
任一条不满足 → **不提议**,退回现有行为。
|
|
91
|
+
|
|
92
|
+
**理由**:无推进的续约只是把卡死延长一个预算周期,还占着并发槽。
|
|
93
|
+
这正是角色 `timeoutMs` 存在的意义。
|
|
94
|
+
|
|
95
|
+
### D2 — 推进度用"产出信号",不用"存活时间"
|
|
96
|
+
|
|
97
|
+
**判据(按可靠度)**:
|
|
98
|
+
|
|
99
|
+
| 优先级 | 信号 | 判读 |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| 1 | session JSONL 中**新增**的 `toolResult` 行数 | 真做事的最强证据(工具有返回) |
|
|
102
|
+
| 2 | session JSONL 中**新增**的 `assistant` 消息数 | 有产出(写了代码/报告) |
|
|
103
|
+
| 3 | 文件系统副作用(工作树内改动数) | 直接证据,但读盘贵 |
|
|
104
|
+
| 4 | `lastJsonlEventAgeMs` 变小 | **不采用**:只说明有 token 流动 |
|
|
105
|
+
|
|
106
|
+
**明确排除**:进程存活、CPU 时间、token 消耗 —— 这些在"卡在一个失败循环里"时同样增长。
|
|
107
|
+
|
|
108
|
+
**阈值**(D2-a,2026-10-24 父会话裁决,修订本节初稿):
|
|
109
|
+
- 自上次续约点起,新增 **`toolResult` 行数 ≥ 3** → 视为有推进
|
|
110
|
+
- 或工作树内新增/修改文件 ≥ **1** → 视为有推进
|
|
111
|
+
- `assistant` 消息**只统计展示,不参与判定**
|
|
112
|
+
|
|
113
|
+
**为什么只有 toolResult 计数、assistant 不计数**:初稿写的是「`toolResult` + `assistant`
|
|
114
|
+
合计 ≥ 3」,但 `assistant` 在死循环里会无限增长 —— 模型反复说同一句话也算 "推进",
|
|
115
|
+
而那恰恰是最需要**不**续约的情形。`toolResult` 意味着**一个工具真的返回了**,是
|
|
116
|
+
"世界被操作过"的证据。因此 assistant 计数保留(给用户看"他产出了多少"),但
|
|
117
|
+
`progressed` 只由 toolResult 与文件改动决定。
|
|
118
|
+
|
|
119
|
+
**为什么是 3**:一次工具调用往返(call + result)+ 一次重试,才够说明"在推进而不是
|
|
120
|
+
卡在第一次失败上"。1 或 2 会把"刚开工就超时"与"稳步推进"混为一谈。
|
|
121
|
+
|
|
122
|
+
### D3 — 续约是**显式选择**,不是自动行为
|
|
123
|
+
|
|
124
|
+
**禁止**自动续约。理由:
|
|
125
|
+
- 自动续约会让"卡死"变成"无限占槽",失去预算的约束力
|
|
126
|
+
- 用户/父会话必须能看见"这个 child 卡了 30 分钟,但确实在推进"这个事实再决定
|
|
127
|
+
|
|
128
|
+
**形式**:超时通知里附带**结构化续约提议**:
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
✗ W2 (worker) failed: terminated — turn budget exhausted (30m)
|
|
132
|
+
progressed: 47 tool results, 12 assistant messages, 6 files changed since spawn
|
|
133
|
+
resume: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
即:**给出判断依据 + 现成的命令**,让父会话/用户一条命令就能续。
|
|
137
|
+
|
|
138
|
+
### D4 — 续约就是 `continue`,不新造机制
|
|
139
|
+
|
|
140
|
+
**禁止**新增 `renew`/`extend` action。续约 = `subagent({action:"continue", name, message})`。
|
|
141
|
+
|
|
142
|
+
理由:
|
|
143
|
+
- `reviveChild`(`index.ts:1844`)已经实现"复用 session 继续",语义完全匹配
|
|
144
|
+
- 新增 action 会分裂两条等价路径,违反单一事实来源
|
|
145
|
+
|
|
146
|
+
**契约要求的是**:让父会话知道**什么时候值得**发这条命令,并把命令**准备好**。
|
|
147
|
+
|
|
148
|
+
### D5 — 角色可声明是否允许续约
|
|
149
|
+
|
|
150
|
+
新增 frontmatter 字段 `renewable`(可选,默认 `true`):
|
|
151
|
+
|
|
152
|
+
```yaml
|
|
153
|
+
# agents/worker.md
|
|
154
|
+
renewable: true # 默认;超时且有推进时提议续约
|
|
155
|
+
renewable: false # 例如 scout:侦察任务超时说明范围没切好,续约是浪费
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**理由**:侦察类角色超时通常意味着任务本身定义有误(范围太大),
|
|
159
|
+
续约只是把错误延后;而实现类角色超时往往是工程量估计不足,续约是对的。
|
|
160
|
+
|
|
161
|
+
### D5-a — 如何区分「超时终止」与「正常结束后的 continue」(2026-10-24 父会话裁决)
|
|
162
|
+
|
|
163
|
+
`continue`/`resume` 对所有已终态的 child 都可用,但**只有被预算切断的**才该消耗续约额度。
|
|
164
|
+
否则「正常失败了、我重试一次」也会吃掉额度,额度就失去意义。
|
|
165
|
+
|
|
166
|
+
**判据(依可靠度排序,取第一个可用者)**:
|
|
167
|
+
|
|
168
|
+
| 优先级 | 判据 | 位置 | 说明 |
|
|
169
|
+
|---|---|---|---|
|
|
170
|
+
| 1 | `execution.stopReason === "toolUse"` | `src/shared/session.ts:912` | **在工具调用中被切断** — 预算耗尽的典型形状 |
|
|
171
|
+
| 2 | 缺 assistant message("missing reply") | `session.ts:12-13`(F29) | hard kill 不写任何 assistant 行 |
|
|
172
|
+
| 3 | `execution.reason` 含 `terminated` | `session.ts:912` | 宿主标注 |
|
|
173
|
+
|
|
174
|
+
**依据**:`src/shared/session.ts:1-14` 的文件头已经把这套语义测过并写死:
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
F29 — "aborted" is never actually written. A graceful interrupt (esc) writes
|
|
178
|
+
error + an errorMessage containing "aborted". A hard kill writes NO
|
|
179
|
+
assistant message at all, so "missing reply" IS the abort signal.
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
即:**被切断的会话在 JSONL 里是可辨识的**,不需要额外记账。
|
|
183
|
+
`shouldRecycleAfterCollect`(`runtime.ts:226`)只区分「终态/非终态」,**不足以**做这个判断。
|
|
184
|
+
|
|
185
|
+
**`stopReason === "stop"` 或 `"length"`** 的正常结束 → 计额度**不**消耗(用户主动重试)。
|
|
186
|
+
|
|
187
|
+
### D6 — 续约预算上限
|
|
188
|
+
|
|
189
|
+
单个 child 的累计续约次数上限 `maxRenewals`(可选,默认 **2**,`0` 表示禁用续约)。
|
|
190
|
+
|
|
191
|
+
理由:给两次重来机会足以覆盖"估计不足",超过则说明任务切分有问题。
|
|
192
|
+
每次续约获得一个**完整**的角色 `timeoutMs`(不累计、不递减)。
|
|
193
|
+
|
|
194
|
+
**满额后**:通知里不再提议,改为明确说明"已达续约上限,请重新切分任务"。
|
|
195
|
+
|
|
196
|
+
### D7 — `wait`/`collect` 超时**绝不**提议续约
|
|
197
|
+
|
|
198
|
+
见 R3。父侧等待超时 ≠ child 失败。此时正确做法是继续 `wait` 或 `collect`
|
|
199
|
+
(child 还活着),不是续约。
|
|
200
|
+
|
|
201
|
+
**验收**:断言这两个超时路径不产生续约提议。
|
|
202
|
+
|
|
203
|
+
### D8 — 推进度基线在续约后重置
|
|
204
|
+
|
|
205
|
+
每次续约成功后,记录新的基线(时间戳 + 当时的行数)。
|
|
206
|
+
下次超时只统计**自基线以来**的新增。
|
|
207
|
+
|
|
208
|
+
**理由**:防止"总共做过很多事"被误判为"刚刚在推进"。
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## §4 实施切分
|
|
213
|
+
|
|
214
|
+
| 单元 | 文件 | 内容 |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
| **W1** | `src/runs/progress-signal.ts`(新) | D2 推进度测量:纯函数 + 可注入的文件读取器 |
|
|
217
|
+
| **W2** | `src/shared/types.ts`, `src/agents/{agents,overrides}.ts` | D5 `renewable` + D6 `maxRenewals` 字段解析与默认值 |
|
|
218
|
+
| **W3** | `src/extension/notify.ts`, `src/extension/runtime.ts` | D3 结构化续约提议渲染(仅超时终止路径)+ D7 排除 wait/collect 超时 |
|
|
219
|
+
| **W4** | `index.ts` | D8 基线记录 + 续约计数 + 满额后的文案 |
|
|
220
|
+
| **W5** | `docs/`, `CHANGELOG.md`, `agents/*.md` | 文档与角色默认值 |
|
|
221
|
+
|
|
222
|
+
**文件归属(禁止越界)**:每个 W 只能改自己那一行的文件。
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## §5 验收
|
|
227
|
+
|
|
228
|
+
| 编号 | 断言 | 归属 |
|
|
229
|
+
|---|---|---|
|
|
230
|
+
| **A1** | 超时终止 + 有推进 + `renewable` → 通知含续约提议与 `continue` 命令 | W3 |
|
|
231
|
+
| **A2** | 超时终止 + **无**推进 → 不提议(续约只是延长卡死) | W1+W3 |
|
|
232
|
+
| **A3** | `wait`/`collect` 超时(child 仍活)→ **不**提议续约(D7) | W3 |
|
|
233
|
+
| **A4** | `renewable: false` 的角色超时 → 不提议 | W2+W3 |
|
|
234
|
+
| **A5** | 续约计数达 `maxRenewals` → 不再提议,文案改为"请重新切分" | W4 |
|
|
235
|
+
| **A6** | 续约成功后基线重置:仅统计新增,不把历史算进推进度(D8) | W4 |
|
|
236
|
+
| **A10** | 正常 `stopReason: "stop"` 后的 `continue` **不**消耗续约额度;`toolUse` 切断才消耗(D5-a) | W4 |
|
|
237
|
+
| **A7** | 推进度阈值:新增 **3 个 toolResult** 或 1 个文件改动为界;assistant 单独不越线(D2-a) | W1 |
|
|
238
|
+
| **A8** | `renew`/`extend` action **不存在**;续约只走 `continue`(D4) | W3 |
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## §6 迁移影响
|
|
243
|
+
|
|
244
|
+
| 影响 | 处置 |
|
|
245
|
+
|---|---|
|
|
246
|
+
| 现有角色文件缺 `renewable` | 默认 `true`,无需改动 |
|
|
247
|
+
| 超时通知文案变化 | `notify.ts` 现有测试需复核;**只增不改**(保留原有行) |
|
|
248
|
+
| `maxRenewals` 计数存放位置 | 写入 `ChildRecord`(父 run.json),不写账本(与 #266 D3 一致) |
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## §7 禁令
|
|
253
|
+
|
|
254
|
+
1. **禁止**自动续约(D3)。
|
|
255
|
+
2. **禁止**新增 `renew`/`extend` action(D4)。
|
|
256
|
+
3. **禁止**用"进程存活/CPU 时间/token 消耗"判断推进(D2)。
|
|
257
|
+
4. **禁止**在 `wait`/`collect` 超时路径提议续约(D7)。
|
|
258
|
+
5. **禁止**让续约累计超过 `maxRenewals`(D6)。
|
|
259
|
+
6. **禁止**把续约计数写进账本(§6)。
|
|
260
|
+
7. **禁止**因续约而改变角色 `timeoutMs` 本身的语义(每次续约是新的完整预算,不是递增)。
|
|
@@ -33,9 +33,12 @@ applicable decision for the child cwd:
|
|
|
33
33
|
|
|
34
34
|
**Ops:** to load project settings / project extensions in an RPC child, either
|
|
35
35
|
`/trust` that cwd first (writes trust.json) or set `defaultProjectTrust=always`.
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
36
|
+
Children inherit host extensions by default (4.0.1), so this matters more than
|
|
37
|
+
it used to: a child loads the parent's discovered extensions unless the card
|
|
38
|
+
subtracts them. Note the two axes are different — inheritance is about *which
|
|
39
|
+
extensions*, trust is about whether a *project* may contribute any at all. A
|
|
40
|
+
child's `--no-extensions` still blocks pi's own project-extension discovery, and
|
|
41
|
+
the inherited list is passed explicitly as `--extension` paths.
|
|
39
42
|
|
|
40
43
|
### Opt-in `--approve` (legion settings)
|
|
41
44
|
|
|
@@ -1,38 +1,48 @@
|
|
|
1
1
|
# In-process AgentSession mode (#197)
|
|
2
2
|
|
|
3
|
-
Default backend for children. **In-process by default**, with
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
3
|
+
Default backend for children. **In-process by default**, with `rpc` used when
|
|
4
|
+
the launch needs an OS worktree (`worktree: true`, which only a `centurion` can
|
|
5
|
+
hold — #214).
|
|
6
|
+
|
|
7
|
+
There is no `spawnMode` config field. The backend is derived from the launch:
|
|
8
|
+
|
|
9
|
+
| Launch needs a worktree? | Backend |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| no | in-process |
|
|
12
|
+
| yes | `rpc` |
|
|
13
|
+
|
|
14
|
+
Since only a `centurion` may hold a worktree, only a centurion can reach
|
|
15
|
+
`rpc`; every other role is in-process. A non-centurion card that asks for
|
|
16
|
+
`worktree: true` is demoted to `worktree: false` with a once-per-run warning,
|
|
17
|
+
which also keeps it in-process.
|
|
8
18
|
|
|
9
19
|
## When to use
|
|
10
20
|
|
|
21
|
+
The choice is not per-role — it follows from whether the work needs a worktree.
|
|
22
|
+
|
|
11
23
|
| Mode | Good for | Avoid when |
|
|
12
24
|
|---|---|---|
|
|
13
|
-
| `inprocess`
|
|
14
|
-
| `rpc`
|
|
25
|
+
| `inprocess` | Short, trusted fan-out; lower spawn latency; simpler approval / UI fan-in | Need OS worktree, separate credentials, crash isolation |
|
|
26
|
+
| `rpc` | Long runs, untrusted tasks, need crash / env / cwd isolation, **worktree** | Cold-start cost dominates |
|
|
15
27
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
the worktree — and since #214 that is only `centurion`: every other role is
|
|
20
|
-
downgraded to `worktree: false` with a one-time warning, so it stays
|
|
21
|
-
in-process.
|
|
28
|
+
Both backends enforce the same legion tree budgets (`maxDepth` /
|
|
29
|
+
`maxChildrenPerNode` / `maxActiveNodes`); the `subagents.inprocess.*` pools apply
|
|
30
|
+
on top and the stricter gate wins.
|
|
22
31
|
|
|
23
32
|
**Non-goals:** no OS worktree isolation; no promise of process crash containment; OpenAaaS Go in-process transport is out of scope.
|
|
24
33
|
|
|
25
34
|
## Config
|
|
26
35
|
|
|
27
|
-
|
|
36
|
+
There is no `spawnMode` key to configure — not in frontmatter, not in
|
|
37
|
+
`agentOverrides`. The old field was removed (4.0.1); a card that still declares
|
|
38
|
+
it is now rejected at load time, because unknown frontmatter is a hard error.
|
|
28
39
|
|
|
29
40
|
```yaml
|
|
30
41
|
# agents/scout.md
|
|
31
42
|
---
|
|
32
43
|
name: scout
|
|
33
44
|
description: Fast read-only recon
|
|
34
|
-
|
|
35
|
-
worktree: false # explicit inprocess + worktree: true is still refused
|
|
45
|
+
worktree: false # a non-centurion asking for true is demoted + warned
|
|
36
46
|
---
|
|
37
47
|
```
|
|
38
48
|
|
|
@@ -40,7 +50,7 @@ worktree: false # explicit inprocess + worktree: true is still refused
|
|
|
40
50
|
{
|
|
41
51
|
"subagents": {
|
|
42
52
|
"agentOverrides": {
|
|
43
|
-
"scout": { "
|
|
53
|
+
"scout": { "worktree": false }
|
|
44
54
|
},
|
|
45
55
|
"inprocess": {
|
|
46
56
|
"maxSpawnsPerSession": 32,
|
|
@@ -62,10 +72,79 @@ worktree: false # explicit inprocess + worktree: true is still refused
|
|
|
62
72
|
| Concurrent alive | `legion.maxActiveNodes` | `inprocess.maxActive` (default **30**; **8** when the block is present without `maxActive`) |
|
|
63
73
|
| Children / node | `legion.maxChildrenPerNode` | `inprocess.maxChildrenPerNode` (default **8**) |
|
|
64
74
|
| Wait timeout | agent `timeoutMs` / wait default | `inprocess.waitTimeoutMs` (no default) |
|
|
75
|
+
| Queue depth | `inprocess.maxQueuedLaunches` (shared by both paths) | `inprocess.maxQueuedLaunches` (default **32**) |
|
|
76
|
+
| Queue wait | `inprocess.launchQueueTimeoutMs` (shared by both paths) | `inprocess.launchQueueTimeoutMs` (default **900000** = 15 min) |
|
|
65
77
|
|
|
66
78
|
Never fall back across columns: in-process limits are read from
|
|
67
79
|
`subagents.inprocess.*` only, never from the `legion.*` keys.
|
|
68
80
|
|
|
81
|
+
### Renewing a budget casualty (#270)
|
|
82
|
+
|
|
83
|
+
An agent's `timeoutMs` is enforced by the host, so pi-legion cannot prevent the
|
|
84
|
+
cut — but it can make the loss recoverable. When a child is terminated **and**
|
|
85
|
+
it measurably progressed, the completion notice ends with a ready-made command:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
✗ W2 (worker) failed (terminated during tool call)
|
|
89
|
+
progressed: 47 tool results, 12 assistant messages, 6 files changed
|
|
90
|
+
renew: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
|
|
91
|
+
renewals: 1/2
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Renewal is `continue` — there is no separate action — so the child resumes from
|
|
95
|
+
its own session file with its context intact. It is **never automatic**: an
|
|
96
|
+
auto-renewed stuck child would hold a concurrency slot indefinitely.
|
|
97
|
+
|
|
98
|
+
Two role frontmatter keys control it:
|
|
99
|
+
|
|
100
|
+
| Key | Default | Meaning |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| `renewable` | `true` | `false` for roles where a timeout means the task was mis-scoped (a timed-out `scout` is a search that was too broad, not work to finish) |
|
|
103
|
+
| `maxRenewals` | `2` | `0` disables renewal. Each renewal is a **fresh full budget**, never an increment |
|
|
104
|
+
|
|
105
|
+
"Progressed" means ≥ 3 new `toolResult` rows or ≥ 1 changed file since the last
|
|
106
|
+
baseline — `assistant` messages are shown but never count: a model looping on the
|
|
107
|
+
same sentence grows that counter without doing any work. With no progress the
|
|
108
|
+
notice says so instead of offering the command, and once the budget is spent it
|
|
109
|
+
tells you to split the task.
|
|
110
|
+
|
|
111
|
+
`wait`/`collect` timeouts never produce a proposal: those return while the child
|
|
112
|
+
is still alive, which is the opposite situation.
|
|
113
|
+
|
|
114
|
+
### Launch admission queue (#266)
|
|
115
|
+
|
|
116
|
+
A launch that hits a **queueable** gate waits in an in-memory queue instead of
|
|
117
|
+
throwing `BUDGET_EXCEEDED`, and is admitted automatically when a slot frees. The
|
|
118
|
+
caller gets `▶ scout-7 (scout) supervisor=inprocess queued(3)` back immediately
|
|
119
|
+
and treats the work as dispatched.
|
|
120
|
+
|
|
121
|
+
| Gate | Queued? | Why |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| `inprocess.maxChildrenPerNode` | ✅ | pure concurrency: the slot always frees |
|
|
124
|
+
| `inprocess.maxActive` | ✅ | same |
|
|
125
|
+
| `legion.maxChildrenPerNode` (`max_children_per_node`) | ✅ | same, RPC path |
|
|
126
|
+
| `legion.maxActiveNodes` (`max_active_nodes`) | ✅ | same, RPC path |
|
|
127
|
+
| `maxDepth` / `maxSpawnsPerSession` / ledger `max_depth` | ❌ | waiting cannot satisfy them; a queue would disguise a permanent failure as a 15-minute delay |
|
|
128
|
+
| `maxChildrenPerNode: 0` | ❌ | 0 means "no children at all" — impossible to satisfy |
|
|
129
|
+
| `parent_not_found`, memory gate, `NAME_TAKEN`, unknown/disabled role, `inprocess`+`worktree`, model scope | ❌ | not a concurrency gate |
|
|
130
|
+
|
|
131
|
+
The two queue bounds are **shared** by both backends on purpose: one scheduler,
|
|
132
|
+
not one per spawn mode. Overflow is an immediate hard refusal
|
|
133
|
+
(`launch queue overflow (32/32)`), a timeout is reported as
|
|
134
|
+
`launch queue timed out after Ns ('<name>')`, and **neither ever creates a
|
|
135
|
+
ledger row, a run directory, a worktree or a session file** — a queued launch has
|
|
136
|
+
reserved nothing yet.
|
|
137
|
+
|
|
138
|
+
Admission is event-driven (a child reaching `retired`/`exited` frees its slot)
|
|
139
|
+
with one `unref`'d fallback recheck, because the ledger can also be freed by
|
|
140
|
+
another process. An `idle` child (turn ended, not yet collected) **still holds
|
|
141
|
+
its slot**, exactly as before.
|
|
142
|
+
|
|
143
|
+
Known limit: the queue is in memory, so a process restart drops it. The leftover
|
|
144
|
+
`queued` records in `run.json` are inert — `collect`/`steer` on one says
|
|
145
|
+
`never started: the launch queue was lost …` instead of `unknown child`, and
|
|
146
|
+
`stop` cleans it up.
|
|
147
|
+
|
|
69
148
|
Omitting an `inprocess.*` key is **not** unlimited. The documented defaults
|
|
70
149
|
mirror `legion.*`, so a deployment with no `subagents.inprocess` block at all
|
|
71
150
|
still runs under `maxDepth: 4` / `maxChildrenPerNode: 8` / `maxActive: 30`.
|
|
@@ -83,8 +162,9 @@ a read-only child's write bans, and a parent read-only role wrongly banned a
|
|
|
83
162
|
`writer` child.
|
|
84
163
|
|
|
85
164
|
So in-process identity travels in an `AsyncLocalStorage` child context instead:
|
|
86
|
-
node id, db path, acceptance role, `allowNested`, `utility`, `spawnMode
|
|
87
|
-
|
|
165
|
+
node id, db path, acceptance role, `allowNested`, `utility`, `spawnMode` (the
|
|
166
|
+
arbitrated backend, for self-reporting), the per-child `budget`, and the nested
|
|
167
|
+
parent path. The guards and the legion runtime read that context, and
|
|
88
168
|
only fall back to env for RPC children, whose process really does own its env.
|
|
89
169
|
|
|
90
170
|
Two consequences worth knowing:
|
|
@@ -107,8 +187,8 @@ Do not replace this with env injection for in-process children.
|
|
|
107
187
|
```
|
|
108
188
|
Orchestrator
|
|
109
189
|
→ RoutingSupervisor (LegionSupervisor)
|
|
110
|
-
├─
|
|
111
|
-
└─
|
|
190
|
+
├─ worktree ⇒ rpc → RpcSupervisor (unchanged)
|
|
191
|
+
└─ otherwise → InProcessSupervisor
|
|
112
192
|
createAgentSession + SessionManager.inMemory
|
|
113
193
|
(tools / model / systemPrompt wired)
|
|
114
194
|
```
|
|
@@ -187,15 +267,14 @@ a decode rate.
|
|
|
187
267
|
|
|
188
268
|
## Refusals
|
|
189
269
|
|
|
190
|
-
- `kind !== "pi"` → `INVALID_PARAMS` regardless of `spawnMode`: only `pi` roles
|
|
191
|
-
are supported, so a non-`pi` role is refused up front and never reaches the
|
|
192
|
-
worktree fallback
|
|
193
|
-
- `worktree: true` + explicit `inprocess` → `INVALID_PARAMS` (an omitted
|
|
194
|
-
`spawnMode` falls back to `rpc` instead)
|
|
195
270
|
- A non-centurion requesting `worktree: true` is **not** a refusal: it is
|
|
196
271
|
downgraded to `worktree: false` with a one-time warning (#214), so the launch
|
|
197
272
|
proceeds in-process. `worktree` is reserved for `centurion`.
|
|
198
|
-
-
|
|
273
|
+
- `worktree: true` reaching the supervisor with a pinned in-process backend →
|
|
274
|
+
`INVALID_PARAMS`. Unreachable from a card now that the field is gone; kept as
|
|
275
|
+
the last line against an internal caller building that shape.
|
|
276
|
+
- Unknown frontmatter (including a leftover `spawnMode:`) → loud throw at parse
|
|
277
|
+
time
|
|
199
278
|
|
|
200
279
|
## Tests
|
|
201
280
|
|