@epoch-agent/plugin-terminal 4.0.0 → 4.1.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/dist/index.d.ts +184 -334
- package/package.json +3 -3
package/dist/index.d.ts
CHANGED
|
@@ -2,22 +2,12 @@ import { BackgroundTaskInfo, EpochTool, EpochPlugin } from '@epoch-agent/protoco
|
|
|
2
2
|
import { SandboxMode, IsolationBackend, SandboxEnforcement, FailureVerdict, ProcessTable, JobsListener, SandboxPolicy } from '@epoch-agent/infra';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
|
-
* 把一次 shell
|
|
5
|
+
* 把一次 shell 调用包进沙箱,并算出这一次要**如实上报**的东西。
|
|
6
6
|
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* PR-1 那一轮还只有一个消费者(管道),挤在一个文件里看不出区别;
|
|
12
|
-
* PR-4 / PR-5 落地之后**三条路径全都要用它**(管道 / 后台 / PTY),
|
|
13
|
-
* 挤着的那份就成了「谁都得 import 那个起进程的文件」。
|
|
14
|
-
*
|
|
15
|
-
* 于是它下沉成一个叶子:三条路径各自 import 它,它谁都不 import。
|
|
16
|
-
*
|
|
17
|
-
* ## 这一层只回答两个问题
|
|
18
|
-
*
|
|
19
|
-
* 1. **argv 要不要换**({@link confineShell} 返回的 `file` / `args`)
|
|
20
|
-
* 2. **这次的边界怎么说出口**({@link SandboxOutcome},以及事后的 `classify`)
|
|
7
|
+
* 这一层只回答两个问题:**argv 要不要换**({@link confineShell} 返回的
|
|
8
|
+
* `file` / `args`)、**这次的边界怎么说出口**({@link SandboxOutcome},以及
|
|
9
|
+
* 事后的 `classify`)。它是个叶子:管道 / 后台 / PTY 三条路径各自 import 它,
|
|
10
|
+
* 它谁都不 import。
|
|
21
11
|
*
|
|
22
12
|
* 「说成人话」是**下一层**的事,在 [sandbox-notice.ts](./sandbox-notice.js) ——
|
|
23
13
|
* 那份整份是给模型读的措辞,所以它单独进了 i18n 的 `SKIP_FILES`,
|
|
@@ -25,11 +15,11 @@ import { SandboxMode, IsolationBackend, SandboxEnforcement, FailureVerdict, Proc
|
|
|
25
15
|
*/
|
|
26
16
|
|
|
27
17
|
/**
|
|
28
|
-
* 这一次跑在什么沙箱里 ——
|
|
18
|
+
* 这一次跑在什么沙箱里 —— **如实上报,不假装**。
|
|
29
19
|
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
20
|
+
* `terminal` 的调用频率比 `code_exec` 高一个量级,「沙箱:已启用」这句话在两个
|
|
21
|
+
* 工具上的含义不一样。让每次执行自己说出边界,比让读文档的人去推「我这一档
|
|
22
|
+
* 大概是什么模式」可靠。
|
|
33
23
|
*/
|
|
34
24
|
interface SandboxOutcome {
|
|
35
25
|
/** 这次按哪一档包的。`null` = 调用方压根没要沙箱(见各路径的 `sandbox` 参数)*/
|
|
@@ -41,23 +31,21 @@ interface SandboxOutcome {
|
|
|
41
31
|
* 没包上的原因,包上了就是 `null`。
|
|
42
32
|
*
|
|
43
33
|
* 六档是六句不同的话,不能合成一个「没有沙箱」:
|
|
44
|
-
* `config-disabled` 是**用户把 `sandbox.terminal`
|
|
34
|
+
* `config-disabled` 是**用户把 `sandbox.terminal` 关了**,
|
|
45
35
|
* `mode-disabled` 是**用户选了不上沙箱的那两档**(`auto` / `bypass`),
|
|
46
36
|
* `no-backend` 是**平台限制**(Windows / 没装 bwrap),
|
|
47
37
|
* `not-requested` 是**调用方没传 policy**(今天只有用例会这样),
|
|
48
|
-
* `escalated`
|
|
49
|
-
*
|
|
50
|
-
* 前两档看着都是「用户自己选的」,但它们是两个正交的轴,分开的理由写在
|
|
51
|
-
* infra 的 `Confinement.reason` 上:说错那一句的代价是用户按着一句
|
|
52
|
-
* 可操作的谎去改档位,而改完照样没有沙箱。
|
|
38
|
+
* `escalated` 是**模型请求了升权、用户单独批了**。
|
|
53
39
|
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
40
|
+
* ⚠️ 前两档都是「用户自己选的」,但它们是两个正交的轴:说错那一句的代价是
|
|
41
|
+
* 用户按着一句可操作的谎去改档位,而改完照样没有沙箱。`escalated` 和
|
|
42
|
+
* `mode-disabled` 的区别是「这一档本来有边界、这一次没有」vs「这一档本来就
|
|
43
|
+
* 承诺不上沙箱」—— 合成一句话后,用户会以为自己切进了 `auto` 档,其实只是
|
|
44
|
+
* 模型请求、他批了一次放宽。
|
|
57
45
|
*/
|
|
58
46
|
skipped: 'config-disabled' | 'mode-disabled' | 'no-backend' | 'not-requested' | 'escalated' | null;
|
|
59
47
|
/**
|
|
60
|
-
*
|
|
48
|
+
* 非零退出时这次失败属于哪一种。
|
|
61
49
|
*
|
|
62
50
|
* ⚠️ **`command-failed` 和 `null` 不是一回事**:前者是「分类器跑过了,
|
|
63
51
|
* 结论是命令自己失败的」,后者是「压根没跑分类器」(退出码为 0,
|
|
@@ -69,116 +57,61 @@ interface SandboxOutcome {
|
|
|
69
57
|
/**
|
|
70
58
|
* 非交互式命令执行 —— 起进程、收两条流、到点杀干净。
|
|
71
59
|
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
* 这个文件的主题只有一个:**别留下孤儿进程**。
|
|
77
|
-
*
|
|
78
|
-
* ## ⚠️ 2026-08-17:它自己也超过 500 行了,所以又拆了一轮(方案 46 PR-4/PR-5)
|
|
79
|
-
*
|
|
80
|
-
* 上面那段文件头解释了「当初为什么从 `index.ts` 拆出来」,却一直没交代
|
|
81
|
-
* **它自己也越过了同一条线**(649 行)。这一轮补上,顺便把该拆的拆了。
|
|
82
|
-
*
|
|
83
|
-
* 拆的判据**不是行数,是关注点**(照方案 55 那一轮 `handlers.ts` / `composer/`
|
|
84
|
-
* 的做法)。原来这个文件塞着三条执行路径 + 沙箱 + 输出上限四样东西:
|
|
85
|
-
*
|
|
86
|
-
* | 拆出去的 | 为什么它是另一个关注点 |
|
|
87
|
-
* | ------------------ | ---------------------------------------------------------- |
|
|
88
|
-
* | [sandbox.ts](./sandbox.js) | 「边界在哪、包没包上」和「别留孤儿进程」是两件事。而且 PR-4/PR-5 之后**三条路径都要用它**,留在这儿等于谁都得 import 那个起进程的文件 |
|
|
89
|
-
* | [pty.ts](./pty.js) | PTY 的进程组语义和另外两条**相反**(`setsid()` 之后它是另一个会话的组长,终端的 Ctrl+C 送不到)。摆在一起读的人得先分辨每段注释在说哪条路 |
|
|
90
|
-
* | [limits.ts](./limits.js) | 输出上限是管道和 PTY 共用的常量。下沉成叶子,`exec ↔ pty` 那个环就不存在了 |
|
|
91
|
-
*
|
|
92
|
-
* 剩下的这一份只讲一条路:**管道(非交互)**。
|
|
60
|
+
* 这个文件只管**管道(非交互)**这一条路:工具定义、危险命令拦截、workdir 校验
|
|
61
|
+
* 在 `index.ts`;`sandbox.ts` / `pty.ts` / `limits.ts` 是另外三个关注点(沙箱、
|
|
62
|
+
* PTY 的进程组语义、输出上限)。
|
|
93
63
|
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
* `node -e "..."` **什么隔离都没有** —— 后者的调用频率高一个量级。
|
|
98
|
-
*
|
|
99
|
-
* ✅ **2026-08-17 起三条路径全包上了**:管道(PR-1)、后台(PR-4,真插入点在
|
|
100
|
-
* [background.ts](./background.js) 的 `startTask()`)、PTY(PR-5,在
|
|
101
|
-
* [pty.ts](./pty.js))。`SANDBOX_EXCLUDES` 那份「点名清单」也跟着空了。
|
|
64
|
+
* 这个文件的主题只有一个:**别留下孤儿进程**。三条执行路径(管道 / 后台 / PTY)
|
|
65
|
+
* 今天都上了沙箱,真插入点在 [background.ts](./background.js) 的 `startTask()`
|
|
66
|
+
* 和 [pty.ts](./pty.js)。
|
|
102
67
|
*/
|
|
103
68
|
|
|
104
69
|
/**
|
|
105
70
|
* 清理这个插件起过的长期子进程 [Hermes]。杀的是整棵树而不是组长。
|
|
106
71
|
*
|
|
107
|
-
* 因为要 `pgrep`(POSIX)/ `taskkill`(Windows)收进程树,它只能是 async
|
|
108
|
-
* 这正是 2026-08-08 之前它一直零调用方的原因(`dispose()` 那时是同步的,于是
|
|
109
|
-
* `terminal(background: true)` 起的进程在宿主退出后全留着)。
|
|
110
|
-
*
|
|
111
|
-
* ⚠️ **今天它在生产路径上又是零调用方了,而这一次是对的。** 方案 60 之后
|
|
112
|
-
* `runtime` 的 `dispose()` 收表走的是 `OwnedProcessTable.release()`(那一下同时
|
|
113
|
-
* 管兜底表的引用计数,这个函数管不了),不再经过这里。留着它是因为它是这个包
|
|
114
|
-
* **发出去的公开 API**(`index.ts` 有 re-export),嵌入宿主可以拿它收自己那张表;
|
|
115
|
-
* 仓库内今天只有 `runtime/__tests__/background-cleanup.test.ts` 在调。
|
|
72
|
+
* 因为要 `pgrep`(POSIX)/ `taskkill`(Windows)收进程树,它只能是 async。
|
|
116
73
|
*
|
|
117
|
-
*
|
|
74
|
+
* ⚠️ **生产路径上没有调用方,而这是对的**:`runtime` 的 `dispose()` 收表走的是
|
|
75
|
+
* `OwnedProcessTable.release()`(那一下同时管兜底表的引用计数,这个函数管不了)。
|
|
76
|
+
* 留着它是因为它是这个包**发出去的公开 API**(`index.ts` 有 re-export),嵌入宿主
|
|
77
|
+
* 可以拿它收自己那张表。
|
|
118
78
|
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
* 判据全文在 [infra/child-process.ts](../../../infra/src/child-process.ts) 的
|
|
123
|
-
* `ProcessTable` 上。
|
|
79
|
+
* ⚠️ **收哪一张表由参数说了算**:收「所有表」会让同一个进程里并存的另一个 runtime
|
|
80
|
+
* 的后台进程和 PTY 一起被收掉,**一个字不报**。判据全文在
|
|
81
|
+
* [infra/child-process.ts](../../../infra/src/child-process.ts) 的 `ProcessTable` 上。
|
|
124
82
|
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
* 「明确不属于任何 runtime」的调用方(用例的清场、plugin-lsp 的 server 池)
|
|
130
|
-
* 留的语义,和这个函数发出去时的含义一致。**不带参数那条路走的是
|
|
131
|
-
* `processFallbackTable().killAll()`,不是 `killAllTrackedProcesses()`** ——
|
|
132
|
-
* 后者收所有表,这里一张都不多收。自己管着一张表的嵌入宿主传自己那张。
|
|
83
|
+
* @param table 收哪一张。**不给 = 收进程级兜底表那一张** —— 那是给「明确不属于
|
|
84
|
+
* 任何 runtime」的调用方(用例的清场、plugin-lsp 的 server 池)留的语义。
|
|
85
|
+
* 不带参数那条路走的是 `processFallbackTable().killAll()`,**不是
|
|
86
|
+
* `killAllTrackedProcesses()`** —— 后者收所有表,这里一张都不多收。
|
|
133
87
|
*/
|
|
134
88
|
declare function cleanupBackgroundProcesses(table?: ProcessTable): Promise<void>;
|
|
135
89
|
|
|
136
90
|
/**
|
|
137
|
-
*
|
|
91
|
+
* 后台命令这一**类作业**的产出方。
|
|
138
92
|
*
|
|
139
93
|
* 一条 `terminal(background: true)` 起的命令在共用作业表里有一格:状态、退出码、
|
|
140
|
-
* 一段环形输出缓冲、以及一个「结束了」的 promise
|
|
141
|
-
*
|
|
142
|
-
*
|
|
143
|
-
*
|
|
144
|
-
* 改造前这里有一整张 `Map<sessionId, Map<taskId, Task>>`,自带环形缓冲、溢出
|
|
145
|
-
* 落盘、`since` 游标、按会话分区、停掉 —— 而 `shell/sessions.ts`(持久会话)
|
|
146
|
-
* 有**逐字同款的第二份**。方案 §三 的判据是「后台跑着的东西不管是什么,
|
|
147
|
-
* 都用同一套控制」,于是整张表下沉进了
|
|
148
|
-
* [infra/jobs.ts](../../../infra/src/jobs.ts),两份并成一份。
|
|
94
|
+
* 一段环形输出缓冲、以及一个「结束了」的 promise。那张表**不在这个文件里**:
|
|
95
|
+
* 它在 [infra/jobs.ts](../../../infra/src/jobs.ts),和持久会话共用一份 ——
|
|
96
|
+
* 判据是「后台跑着的东西不管是什么,都用同一套控制」。
|
|
149
97
|
*
|
|
150
|
-
*
|
|
98
|
+
* 留在这儿的都是**只有后台命令才有的那些**:
|
|
151
99
|
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
156
|
-
* | 非零退出时给沙箱定性 | 要读退出码和输出,是这一类特有的事后判定 |
|
|
157
|
-
* | → `BackgroundTaskInfo` | 那个形状在 protocol,而 **infra 依赖不到 protocol** |
|
|
100
|
+
* - `MAX_TASKS` 名额判定 —— 每类作业各有取值(后台命令 8,持久会话 4)
|
|
101
|
+
* - `confineShell` + 起进程 —— 沙箱和 shell 拼装是 plugin 的知识,infra 不该认识它
|
|
102
|
+
* - 非零退出时给沙箱定性 —— 要读退出码和输出,是这一类特有的事后判定
|
|
103
|
+
* - → `BackgroundTaskInfo` —— 那个形状在 protocol,而 **infra 依赖不到 protocol**
|
|
158
104
|
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
105
|
+
* 最后一条不只是分层洁癖:`BackgroundTaskInfo` 是**发给宿主的线上形状**(server 的
|
|
106
|
+
* `/api/sessions/:id/tasks`、Web 检视面板、TUI 的 `/tasks`),而作业表装着两类东西。
|
|
107
|
+
* 宿主那两个口子({@link listTasks} / {@link getTask})因此**报整张表**:`command`
|
|
108
|
+
* 只在 `'command'` 那一档才有(判据在 `protocol/src/task.ts` 那三格上),填 `label`
|
|
109
|
+
* 进 `command` 就是「一个叫 command 的字段里装着一个工作目录」。
|
|
162
110
|
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
* 那一类,「宿主那一侧要不要显示持久会话,是一次界面决定,不在这一轮」。
|
|
168
|
-
*
|
|
169
|
-
* **那句判据一个字都没被推翻,被推翻的是「所以只报一类」这个结论。** 假话来自
|
|
170
|
-
* `command` 那一个字段填不出实话,而修法不是藏起半张表,是**把形状改对**:
|
|
171
|
-
* `BackgroundTaskInfo` 现在有 `kind` + `label`,`command` 只在 `'command'`
|
|
172
|
-
* 那一档才有(判据全文在 `protocol/src/task.ts` 那三格上)。
|
|
173
|
-
*
|
|
174
|
-
* 于是这两个口子改成**报整张表**,而那次「界面决定」也做了:三处界面按 `kind`
|
|
175
|
-
* 各画一枚记号,不加新列。
|
|
176
|
-
*
|
|
177
|
-
* ⚠️ **给模型的那一侧刻意没跟着变**:`task_*` 四个工具照旧走 kind 无关的路
|
|
178
|
-
* ([tasks.ts](./tasks.ts)),而每轮那条 system note
|
|
179
|
-
* (`core/src/agent/task-notice.ts`)**显式过滤成只报 `command`** —— 模型已经有
|
|
180
|
-
* `shell_list` 可以自己问,把持久会话塞进那条 note 是多一份重复、还每轮花 token。
|
|
181
|
-
* 那儿写着同一条理由,别当成漏了。
|
|
111
|
+
* ⚠️ **给模型的那一侧刻意不是这样**:`task_*` 四个工具照旧走 kind 无关的路
|
|
112
|
+
* ([tasks.ts](./tasks.ts)),而每轮那条 system note(`core/src/agent/task-notice.ts`)
|
|
113
|
+
* **显式过滤成只报 `command`** —— 模型已经有 `shell_list` 可以自己问,把持久会话塞进
|
|
114
|
+
* 那条 note 是多一份重复、还每轮花 token。
|
|
182
115
|
*
|
|
183
116
|
* ## 三条上限,各挡各的
|
|
184
117
|
*
|
|
@@ -188,69 +121,50 @@ declare function cleanupBackgroundProcesses(table?: ProcessTable): Promise<void>
|
|
|
188
121
|
* | 单任务输出 256KB | 一个刷屏的 `pnpm dev` 跑一夜把内存吃光 |
|
|
189
122
|
* | `task_output` 单次 8KB | 取一次输出就把上下文塞满 |
|
|
190
123
|
*
|
|
191
|
-
*
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
* `
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
207
|
-
*
|
|
208
|
-
* `
|
|
209
|
-
*
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
* ⚠️ 别把它写成「另一个 runtime 的 dispose 会把这个进程收走」—— 那句话在这儿
|
|
223
|
-
* 活过一轮(2026-08-21 改掉),它描述的是方案 60 **修掉的**那个旧行为。
|
|
224
|
-
*
|
|
225
|
-
* ## ⚠️ 会话被冷却(`live: false`)时:这批任务**一个字都不动**
|
|
226
|
-
*
|
|
227
|
-
* 冷却(`SessionHub` 的 LRU + `SessionFactory.release()`)是「把内存还回去」。
|
|
228
|
-
* 作业表不在被放掉的那一批里,判据与 `release()` 里「工作区绑定不在这里解」
|
|
229
|
-
* 逐字同款 —— 会话可以被释放,而**进程还在跑**是一个仍然成立的事实,
|
|
230
|
-
* 且这张表是唯一还能停掉它的把手。跟着冷却清掉的话,那几个 `pnpm dev` 会一直
|
|
231
|
-
* 烧到进程退出,而没有任何人能报出它们的存在;跟着冷却**杀掉**更糟 ——
|
|
232
|
-
* 用户开第 9 个标签页,第 1 个会话跑了二十分钟的构建就没了。
|
|
233
|
-
*
|
|
234
|
-
* ⚠️ **真删会话(`DELETE /api/sessions/:id`)那条路 2026-10-29 起会收这一格了** ——
|
|
235
|
-
* `SessionControl.delete` 调 infra 的 `stopSessionJobs(sessionId)`(判据在它的
|
|
236
|
-
* JSDoc 上)。在这之前这里写的是「今天没有收」,那份判断的条件已经变了。
|
|
237
|
-
*
|
|
238
|
-
* ⚠️ **冷却(上面那一节)和真删是两件事,别把这条改动读成冷却也会杀进程**:
|
|
239
|
-
* 冷却一个字都没变,作业表照旧不动。判据是「这段会话还会回来」和「这段会话
|
|
240
|
-
* 不会再回来」的差别 —— 前者要保住那个把手,后者连会话都没了。
|
|
124
|
+
* 第二条用**环形缓冲**(丢头保尾)而不是「满了就截断」,溢出的那部分落盘;判据在
|
|
125
|
+
* `infra/jobs.ts` 的 `append()`。「别的会话的 id 一律当不存在」由同一张表的 `jobIn()`
|
|
126
|
+
* 执行,`__tests__/session-scope.test.ts` 盯着它。
|
|
127
|
+
*
|
|
128
|
+
* ⚠️ **同时 8 个**是每会话一份:满了时给的建议是「先用 `task_stop` 停掉一个」,而按
|
|
129
|
+
* 会话分之后别人的任务这个会话**够不着** —— 一条做不到的建议比没有建议更坏。代价:
|
|
130
|
+
* 进程里的总数是 `8 × 活跃会话数`;真要收住,那是**另一条**进程级上限(和这一条并存)。
|
|
131
|
+
*
|
|
132
|
+
* ## ⚠️ 进程退出与冷却
|
|
133
|
+
*
|
|
134
|
+
* 进程退出时的清理**不走作业表**:真正的回收是 infra 那张按 pid 记的长期子进程表,
|
|
135
|
+
* 宿主 `dispose()`(走 `OwnedProcessTable.release()`)收的就是它,分工见
|
|
136
|
+
* `infra/jobs.ts` 文件头。那张表按 `sessionId` 分给各个 runtime
|
|
137
|
+
* (`processTableFor(sessionId)`),这里起进程**必须走那条路由** —— 走
|
|
138
|
+
* `startLongLivedProcess()` 自由函数会登记进**进程级兜底表**,后果是**收得晚,不是
|
|
139
|
+
* 收错人**:兜底表要等最后一个 runtime `release()` 把引用计数减到 0 才收,于是这个会话
|
|
140
|
+
* 的 runtime dispose 之后进程还挂着,直到整个 epoch 进程收摊(infra 刻意选的方向:
|
|
141
|
+
* 漏认领 = 泄漏一会儿,而不是静默端掉别人的构建)。判据在 `processTableFor()` 上,钉它
|
|
142
|
+
* 的用例是 `runtime/__tests__/process-table-ownership.test.ts` 第五节。
|
|
143
|
+
* ⚠️ 别把它写成「另一个 runtime 的 dispose 会把这个进程收走」:那描述的是已经
|
|
144
|
+
* 修掉的旧行为。今天漏认领的后果只是「收得晚」。
|
|
145
|
+
*
|
|
146
|
+
* 会话被冷却(`live: false`)时这批任务**一个字都不动**:冷却(`SessionHub` 的 LRU +
|
|
147
|
+
* `SessionFactory.release()`)还的是内存,而**进程还在跑**是一个仍然成立的事实,这张
|
|
148
|
+
* 表是唯一还能停掉它的把手。跟着清掉,那几个 `pnpm dev` 会一直烧到进程退出而没人报得
|
|
149
|
+
* 出它们的存在;跟着**杀掉**更糟 —— 用户开第 9 个标签页,第 1 个会话跑了二十分钟的
|
|
150
|
+
* 构建就没了。
|
|
151
|
+
*
|
|
152
|
+
* ⚠️ **真删会话(`DELETE /api/sessions/:id`)会收这一格**:`SessionControl.delete` 调
|
|
153
|
+
* infra 的 `stopSessionJobs(sessionId)`。判据是「这段会话还会回来」和「不会再回来」的
|
|
154
|
+
* 差别,别把这条读成冷却也会杀进程。
|
|
241
155
|
*/
|
|
242
156
|
|
|
243
|
-
/**
|
|
157
|
+
/** **每个会话**同时最多几个在跑(判据见文件头) */
|
|
244
158
|
declare const MAX_TASKS = 8;
|
|
245
159
|
/**
|
|
246
160
|
* 起一个后台任务。名额满了返回一句话而不是抛。
|
|
247
161
|
*
|
|
248
162
|
* @param sessionId 这个任务归谁(`ToolContext.sessionId`)。**必填**:一条不知道
|
|
249
|
-
* 属于谁的后台任务在作业表里没有位置 ——
|
|
250
|
-
*
|
|
251
|
-
* @param homeDir 数据目录(`ToolContext.homeDir
|
|
252
|
-
*
|
|
253
|
-
* @param sandbox
|
|
163
|
+
* 属于谁的后台任务在作业表里没有位置 —— 它要么被所有会话看见,要么谁都看不见。
|
|
164
|
+
* 它同时决定溢出的输出落进哪个 artifact 目录
|
|
165
|
+
* @param homeDir 数据目录(`ToolContext.homeDir`)。**不能省**:省掉就落进全局
|
|
166
|
+
* `~/.epoch/artifacts/`,而宿主的界面从 `<homeDir>/artifacts/` 读
|
|
167
|
+
* @param sandbox 这次的沙箱边界。**不传 = 不上沙箱**,如实标成
|
|
254
168
|
* `skipped: 'not-requested'`。口径和 `runCommand` / `runCommandPty` 逐字一致
|
|
255
169
|
*/
|
|
256
170
|
declare function startTask(sessionId: string, command: string, cwd?: string, homeDir?: string, sandbox?: SandboxPolicy): {
|
|
@@ -260,17 +174,15 @@ declare function startTask(sessionId: string, command: string, cwd?: string, hom
|
|
|
260
174
|
error: string;
|
|
261
175
|
};
|
|
262
176
|
/**
|
|
263
|
-
* 一个任务当下的沙箱状况。`task_output` 用它把「被沙箱挡了 /
|
|
264
|
-
*
|
|
265
|
-
*
|
|
177
|
+
* 一个任务当下的沙箱状况。`task_output` 用它把「被沙箱挡了 / 沙箱没起来」说成另一句话
|
|
178
|
+
* —— 后台失败和前台失败一样需要这个区分,而且更需要:前台失败时模型手里有 stderr,
|
|
179
|
+
* 后台失败时它得先想起来去 `task_output` 取。
|
|
266
180
|
*/
|
|
267
181
|
declare function taskSandbox(sessionId: string, id: string): SandboxOutcome | undefined;
|
|
268
182
|
/**
|
|
269
|
-
*
|
|
270
|
-
*
|
|
271
|
-
*
|
|
272
|
-
* 落点是 `BackgroundTaskInfo` 那个线上形状)。它 2026-08-26 之前只报 `command`,
|
|
273
|
-
* 理由和翻案的判据都在文件头那一节。
|
|
183
|
+
* 这个会话起过的**全部作业**,**给宿主的**口子(runtime 转出去给 server / TUI / Web
|
|
184
|
+
* 检视面板,落点是 `BackgroundTaskInfo` 那个线上形状)。为什么是整张表、而给模型那一侧
|
|
185
|
+
* 不是,见文件头。
|
|
274
186
|
*/
|
|
275
187
|
declare function listTasks(sessionId: string): BackgroundTaskInfo[];
|
|
276
188
|
interface TaskOutputResult {
|
|
@@ -285,14 +197,9 @@ interface TaskOutputResult {
|
|
|
285
197
|
hasMore: boolean;
|
|
286
198
|
}
|
|
287
199
|
/**
|
|
288
|
-
*
|
|
289
|
-
*
|
|
290
|
-
*
|
|
291
|
-
* 判据在 {@link actionableJob} 上那一节:**取输出是「看」,不是「动」**。
|
|
292
|
-
* 一格在检视面板上列得出来、点开却永远是空的,那是把可见性做了一半。
|
|
293
|
-
*
|
|
294
|
-
* `since` 是绝对偏移,语义和实现都在 `infra/jobs.ts` 的 `readJob()`
|
|
295
|
-
* —— 那一层本来就是 kind 无关的,所以这里放宽只是把一道多余的闸撤掉。
|
|
200
|
+
* 取增量输出,**也认持久会话**(判据见 {@link actionableJob}:取输出是「看」)。
|
|
201
|
+
* `since` 是绝对偏移,语义和实现都在 `infra/jobs.ts` 的 `readJob()` —— 那一层本来
|
|
202
|
+
* 就是 kind 无关的,这里只是不再多设一道闸。
|
|
296
203
|
*/
|
|
297
204
|
declare function taskOutput(sessionId: string, id: string, since?: number): TaskOutputResult | undefined;
|
|
298
205
|
/** 停掉一个任务(杀整棵树)。已经结束的、别的会话的都返回 false */
|
|
@@ -315,80 +222,46 @@ declare function waitTask(sessionId: string, id: string, timeoutMs: number, sign
|
|
|
315
222
|
readonly aborted: boolean;
|
|
316
223
|
}): Promise<TaskWaitResult | undefined>;
|
|
317
224
|
/**
|
|
318
|
-
* `/resume` 换了会话 id
|
|
225
|
+
* `/resume` 换了会话 id,这一格跟着搬。
|
|
319
226
|
*
|
|
320
|
-
*
|
|
321
|
-
*
|
|
322
|
-
*
|
|
323
|
-
* 而它还在跑 —— 一个停不掉也报不出来的进程,比一条错误归属的记录坏得多。
|
|
227
|
+
* 判据同 `build.ts` 里紧挨着的 `workspaces.seed(id, …)`:**resume 只是把另一段对话接上
|
|
228
|
+
* 这个引擎,它照旧跑在这个进程、这个工作区里**。不搬的话,TUI 里 `/resume` 一下,刚才
|
|
229
|
+
* 起的那条 `pnpm dev` 从 `/tasks` 里消失而它还在跑 —— 一个停不掉也报不出来的进程。
|
|
324
230
|
*
|
|
325
|
-
* ⚠️ **只搬 `command` 和 `agent
|
|
326
|
-
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
* 后台子 agent(2026-10-26)**要搬**,判据和上面那条 `pnpm dev` 逐字同款:
|
|
331
|
-
* 它可以跑好几分钟,`/resume` 一下就从 `task_list` 里消失、也停不掉,
|
|
332
|
-
* 而它比一条命令更贵(每个子任务花的是模型的钱)。
|
|
231
|
+
* ⚠️ **只搬 `command` 和 `agent`**:持久会话不搬(那个 venv 还算不算「这段对话的」是
|
|
232
|
+
* 要单独判的产品决定),而两类住在同一张表里 —— 点名 kind 就是那次刻意不作为的落点,
|
|
233
|
+
* 不点名的话它会在这一轮被静默改掉。后台子 agent **要搬**,判据同上,而且它比一条命令
|
|
234
|
+
* 更贵(每个子任务花的是模型的钱)。
|
|
333
235
|
*/
|
|
334
236
|
declare function rekeyTasks(from: string, to: string): void;
|
|
335
237
|
/**
|
|
336
|
-
*
|
|
337
|
-
*
|
|
338
|
-
* 宿主要的第三个口子 —— 前两个({@link listTasks} / {@link taskOutput})答的是
|
|
339
|
-
* 「现在是什么样」,这一个答的是「什么时候该再问一遍」。少了它,`epoch web`
|
|
340
|
-
* 检视面板「输出」那一格只在回合状态跃迁时才重取,于是一个会话空闲着的时候,
|
|
341
|
-
* 一条自己跑完(或者崩了)的构建会**无限期**停在「运行中」上。
|
|
238
|
+
* 订阅「哪个会话的任务清单变了」。回传退订函数。
|
|
342
239
|
*
|
|
343
|
-
*
|
|
344
|
-
*
|
|
240
|
+
* 宿主要的第三个口子 —— 前两个({@link listTasks} / {@link taskOutput})答的是「现在
|
|
241
|
+
* 是什么样」,这一个答的是「什么时候该再问一遍」。少了它,`epoch web` 检视面板「输出」
|
|
242
|
+
* 那一格只在回合状态跃迁时才重取,于是一个会话空闲着的时候,一条自己跑完(或者崩了)
|
|
243
|
+
* 的构建会**无限期**停在「运行中」上。
|
|
345
244
|
*
|
|
346
245
|
* ## ⚠️ 这一个**不过 {@link actionableJob} 那道闸**
|
|
347
246
|
*
|
|
348
|
-
*
|
|
349
|
-
*
|
|
350
|
-
*
|
|
351
|
-
* `JobsListener`)。要过就得把 kind 带上来,而那是在这条通道上开一个只有这一处
|
|
352
|
-
* 用得上的载荷。
|
|
353
|
-
*
|
|
354
|
-
* 代价是一次多余的重取:只起过持久会话、没起过后台命令的会话上,`shell_send`
|
|
355
|
-
* 会让宿主重取一次任务清单。那一发本来就要发(面板里那一格是持久会话自己的)。
|
|
247
|
+
* 同「可见性和生命周期是两件事」:检视面板列得出持久会话,那么它的增删也得让面板知道。
|
|
248
|
+
* 而且这里也**没法**过 —— 载荷只有 `sessionId`,到这一层已经不知道是哪一格变的了,
|
|
249
|
+
* 要过就得把 kind 带上来,那是开一个只有这一处用得上的载荷。代价是一次多余的重取。
|
|
356
250
|
*/
|
|
357
251
|
declare function observeTasks(listener: JobsListener): () => void;
|
|
358
252
|
/**
|
|
359
253
|
* 忘掉**所有**会话的后台命令记录(**不杀进程**)。只给用例用。
|
|
360
254
|
*
|
|
361
|
-
*
|
|
362
|
-
*
|
|
363
|
-
* `
|
|
364
|
-
*
|
|
365
|
-
*
|
|
366
|
-
*
|
|
367
|
-
*
|
|
368
|
-
*
|
|
369
|
-
*
|
|
370
|
-
*
|
|
371
|
-
* > 该有的处置是删会话时连同它们一起停掉 —— 那是一次真的杀进程,语义上和
|
|
372
|
-
* > `hub.unregister()` 里「放弃挂起的审批 + 中止在跑的回合」同一档。
|
|
373
|
-
* >
|
|
374
|
-
* > 这一轮**没做**,两个理由:入口在 `server/src/api.ts` 的删会话处理里,不在
|
|
375
|
-
* > 这一轮的文件所有权内(.epoch/plans/30 §十二那条规矩);而且「删会话要不要
|
|
376
|
-
* > 杀掉它起的构建」是一次产品决定。要收的话在 infra 那边加一个
|
|
377
|
-
* > `stopSessionJobs(sessionId)`(遍历那一格 `stopJob`),在删会话那条路上调一次
|
|
378
|
-
* > —— **不是** `clearAllJobs` 的会话版:只忘掉记录而不杀进程,正好是上面说的那个洞。
|
|
379
|
-
*
|
|
380
|
-
* 那两个理由各自的下场:
|
|
381
|
-
*
|
|
382
|
-
* - 第一个(文件所有权)**早已不成立** —— 那轮的并行分支早合完了;
|
|
383
|
-
* - 第二个(产品决定)**判错了对象**。「删会话要不要杀掉它起的构建」确实是
|
|
384
|
-
* 一次产品决定;而「删完之后它还在跑,并且从此谁都停不掉它」不是 —— 后者
|
|
385
|
-
* 没有选项,是一条失控。实际落地的是**只收掉那个失控**(停掉全部 + 忘掉
|
|
386
|
-
* 记录),没有做「问用户要不要连构建一起停」那个 UI,那是另一笔。
|
|
387
|
-
*
|
|
388
|
-
* 上面那段原文里那句「**不是** `clearAllJobs` 的会话版」正是这一笔的判据:
|
|
389
|
-
* 照着写一个只忘记录的会话版,得到的还是那个洞。
|
|
390
|
-
*
|
|
391
|
-
* ⚠️ **和冷却无关**:同一份文件头上一节那批「冷却时一个字都不动」一个字没变。
|
|
255
|
+
* 它清的是共用表里 `command` 那一类,**不碰持久会话那一类**(判据见 infra
|
|
256
|
+
* `clearAllJobs` 的 `kinds` 参数)。用例清场的顺序是先 `killAllTrackedProcesses()` 再
|
|
257
|
+
* 这一下(生产路径走的是 `OwnedProcessTable.release()`,不是它)。
|
|
258
|
+
*
|
|
259
|
+
* ⚠️ **`DELETE /api/sessions/:id` 那条路会收这一格**,走的是 infra 的
|
|
260
|
+
* `stopSessionJobs(sessionId)`。只忘记录而不杀进程是一个洞:那几个后台任务从此没有任何
|
|
261
|
+
* 界面看得见,而进程一直跑到 epoch 退出 —— 照着写一个「只清记录的会话版」得到的还是
|
|
262
|
+
* 那个洞。
|
|
263
|
+
*
|
|
264
|
+
* ⚠️ **和冷却无关**:冷却时那批任务一个字都不动(见文件头)。
|
|
392
265
|
*/
|
|
393
266
|
declare function clearAllTasks(): void;
|
|
394
267
|
/** 一行摘要,宿主展示用 */
|
|
@@ -471,31 +344,23 @@ interface ShellReadResult {
|
|
|
471
344
|
}
|
|
472
345
|
|
|
473
346
|
/**
|
|
474
|
-
* 持久 shell
|
|
347
|
+
* 持久 shell 会话这一**类作业**的产出方。
|
|
475
348
|
*
|
|
476
349
|
* 一个 `shell_open` 起的 PTY 在共用作业表里有一格:进程、状态、一段环形输出
|
|
477
|
-
*
|
|
478
|
-
*
|
|
479
|
-
* ## ✅ 2026-08-20(PR-3):这张表和后台任务表**并成了一张**
|
|
480
|
-
*
|
|
481
|
-
* 改造前这里有一整张 `Map<sessionId, Map<shellId, Shell>>`,而 `background.ts`
|
|
482
|
-
* 有**逐字同款的第二份**(环形缓冲、溢出落盘、`since` 游标、按会话分区、停掉)。
|
|
483
|
-
* PR-1 的落地记录里明写着「合出来的那份该住 infra,而 **PR-3 正要把整张作业表
|
|
484
|
-
* 下沉到那里**」—— 这一轮兑现了:表在
|
|
485
|
-
* [infra/jobs.ts](../../../../infra/src/jobs.ts),两份并成一份。
|
|
350
|
+
* 缓冲、上次活动时间。表本身在 [infra/jobs.ts](../../../../infra/src/jobs.ts),
|
|
351
|
+
* 和后台任务表是**同一张**。
|
|
486
352
|
*
|
|
487
|
-
* ⚠️
|
|
488
|
-
*
|
|
489
|
-
*
|
|
490
|
-
*
|
|
491
|
-
*
|
|
492
|
-
* `task_wait s1` 会**立刻**说一句实话,而不是把整轮卡满超时。
|
|
353
|
+
* ⚠️ **表合并了,语义没合并**:后台任务是「起来不管了」,持久会话是
|
|
354
|
+
* 「起来还要接着聊」—— 前者只读输出,后者要往里发东西。所以 `shell_send` /
|
|
355
|
+
* `shell_read` 这一族独立存在,合并的只是「列出来 / 读输出 / 停掉」那一套控制
|
|
356
|
+
* (infra 的 `stopJob`)。落在代码上:`kind: 'shell'` 这一格的 `terminates: false`,
|
|
357
|
+
* 于是 `task_wait s1` 会**立刻**说一句实话,而不是把整轮卡满超时。
|
|
493
358
|
*
|
|
494
359
|
* 这个文件剩下的是**只有持久会话才有的那些**:起 PTY、ConPTY 前导、空闲回收、
|
|
495
360
|
* pty 树的收法、以及 → `ShellInfo` 的投影(那个形状里的 `shell` 字段是「真正
|
|
496
361
|
* 起的那个可执行文件」,作业表不认识它,所以它住在 {@link ShellDetail})。
|
|
497
362
|
*
|
|
498
|
-
* ## 四条上限,照 `background.ts`
|
|
363
|
+
* ## 四条上限,照 `background.ts` 的口径(不发明新数字,取值可以不同)
|
|
499
364
|
*
|
|
500
365
|
* | 上限 | 后台任务 | 这里 | 为什么不同 |
|
|
501
366
|
* | ---------------------- | ---------- | ----------- | ---------------------------------------------- |
|
|
@@ -506,12 +371,11 @@ interface ShellReadResult {
|
|
|
506
371
|
*
|
|
507
372
|
* ## ⚠️ 进程退出时的回收:**靠 infra 那张按 pid 记的表,不靠作业表**
|
|
508
373
|
*
|
|
509
|
-
* 每个 PTY
|
|
510
|
-
*
|
|
374
|
+
* 每个 PTY 在起来的那一刻就登记进去,宿主 `dispose()` 走
|
|
375
|
+
* `OwnedProcessTable.release()` 收的就是那一张。
|
|
511
376
|
*
|
|
512
|
-
* ⚠️
|
|
513
|
-
*
|
|
514
|
-
* 它进的是进程级兜底表,而兜底表只在**最后一个** runtime 把引用计数减到 0 时才收,
|
|
377
|
+
* ⚠️ **登记必须走 `processTableFor(sessionId)`,不能走 `trackForeignProcess()`**:
|
|
378
|
+
* 后者进的是进程级兜底表,而兜底表只在**最后一个** runtime 把引用计数减到 0 时才收,
|
|
515
379
|
* 于是这个 shell 会一直挂到整个 epoch 进程里最后一个 runtime 走 —— **收得晚,
|
|
516
380
|
* 不是被别人收走**(漏认领的方向是刻意这么选的,判据在 infra 的
|
|
517
381
|
* `processTableFor()` 上)。
|
|
@@ -520,8 +384,6 @@ interface ShellReadResult {
|
|
|
520
384
|
* 内核直接发给整组,就算我们的清理代码一行都没跑也不残留。PTY **没有这个保底** ——
|
|
521
385
|
* `forkpty()` 里 `setsid()` 过,它是另一个会话的组长。判据全文在
|
|
522
386
|
* [infra/child-process.ts](../../../../infra/src/child-process.ts) 的文件头那张表。
|
|
523
|
-
* 方案 §四 验收 12 量的就是这一条:把那一行登记摘掉 →
|
|
524
|
-
* 验收 8(Ctrl+C 之后没有孤儿 shell)当场变红。
|
|
525
387
|
*
|
|
526
388
|
* ⚠️ **摘登记必须在 `killPtyTree` 之后**,不能在之前 —— 判据写在
|
|
527
389
|
* {@link afterEnd} 上,那也是 infra 的 `endJob` 刻意不提供 `onEnd` 钩子的原因。
|
|
@@ -546,12 +408,11 @@ interface ShellOpened {
|
|
|
546
408
|
/**
|
|
547
409
|
* 开一个持久会话。
|
|
548
410
|
*
|
|
549
|
-
* @param sessionId 这个会话归谁(`ToolContext.sessionId
|
|
550
|
-
* `startTask`:一条不知道属于谁的持久 shell 在作业表里没有位置
|
|
411
|
+
* @param sessionId 这个会话归谁(`ToolContext.sessionId`)。**必填**
|
|
551
412
|
* @param cwd 工作目录。**边界校验不在这一层**(工具层用 infra 的 `isInWorkspace`
|
|
552
413
|
* 判过了,和 `terminal` 同一条),这里收到的已经是解析好的绝对路径
|
|
553
414
|
* @param homeDir 数据目录(`ToolContext.homeDir`)。决定溢出的输出落进哪个
|
|
554
|
-
* artifact 目录 ——
|
|
415
|
+
* artifact 目录 —— **不能省**
|
|
555
416
|
* @param sandbox 这次的沙箱边界。**不传 = 不上沙箱**,如实标成 `not-requested`;
|
|
556
417
|
* 工具那条真实路径每次都传,且传的是**和 `terminal` 同一个** `sandboxPolicyFor()`
|
|
557
418
|
*/
|
|
@@ -564,20 +425,17 @@ interface ShellGone {
|
|
|
564
425
|
* 往一个会话里发一段输入,等 `waitMs` 之后把这段时间的输出交回去。
|
|
565
426
|
*
|
|
566
427
|
* `wait` 是「等多久再返回输出」而不是「等命令结束」—— 持久会话没有「结束」这个
|
|
567
|
-
*
|
|
568
|
-
* 游标接着上次的 `nextCursor` 走。
|
|
428
|
+
* 状态。等不够就再 `shell_read` 一次,游标接着上次的 `nextCursor` 走。
|
|
569
429
|
*
|
|
570
430
|
* ⚠️ **末尾的换行由调用方负责**:`shell_send({ input: 'pwd' })` 和 `'pwd\n'`
|
|
571
|
-
*
|
|
572
|
-
*
|
|
573
|
-
*
|
|
574
|
-
* 那条路唯一的走法。
|
|
431
|
+
* 是两回事,前者只是把字符打进去、命令没被执行。这一层刻意**不替调用方补** ——
|
|
432
|
+
* 补的话 `\x03`(Ctrl+C)会变成「Ctrl+C 加一个回车」,而那是「用 shell_send
|
|
433
|
+
* 覆盖 signal」那条路唯一的走法。
|
|
575
434
|
*
|
|
576
|
-
* ⚠️
|
|
435
|
+
* ⚠️ 但**已有的换行要翻译成这个平台上的回车键**({@link asKeystrokes}):
|
|
577
436
|
* ConPTY 的控制台行输入只认 `\r`,Windows 上原样写 `\n` 的后果是
|
|
578
|
-
*
|
|
579
|
-
*
|
|
580
|
-
* 所以上面那条 Ctrl+C 的约束一个字都没变。
|
|
437
|
+
* 「命令回显出来了、一次都没执行」。只改写、不追加,所以上面那条 Ctrl+C 的
|
|
438
|
+
* 约束一个字都没变。
|
|
581
439
|
*/
|
|
582
440
|
declare function sendToShell(sessionId: string, id: string, input: string, waitMs: number): Promise<ShellReadResult | ShellGone>;
|
|
583
441
|
/** 增量读。`since` 的语义和 `task_output` 逐字一致(绝对偏移) */
|
|
@@ -585,11 +443,10 @@ declare function readShell(sessionId: string, id: string, since?: number): Shell
|
|
|
585
443
|
/**
|
|
586
444
|
* 关掉一个会话(杀整棵进程树)。已经不在跑的返回 `false`。
|
|
587
445
|
*
|
|
588
|
-
* 别的会话的 id 也返回 `false
|
|
589
|
-
* `stopTask`:这是这一族里真会动手的那个。
|
|
446
|
+
* 别的会话的 id 也返回 `false`,和「已经关了」同一个出口。
|
|
590
447
|
*
|
|
591
448
|
* ⚠️ **kind 无关的 `task_stop` 走的是同一条路**(infra 的 `stopJob`),所以
|
|
592
|
-
*
|
|
449
|
+
* 「关掉」这件事只有一个实现。
|
|
593
450
|
*/
|
|
594
451
|
declare function closeShell(sessionId: string, id: string): Promise<boolean>;
|
|
595
452
|
/** 这个会话开过的持久 shell,**只有这个会话的** */
|
|
@@ -599,12 +456,11 @@ declare function listShells(sessionId: string): ShellInfo[];
|
|
|
599
456
|
*
|
|
600
457
|
* **用例**清场里的正确顺序是**先** infra 的 `killAllTrackedProcesses()`(用例要的
|
|
601
458
|
* 就是它那个跨表口径)**再**这一下:反过来的话那几个 pty 还活着,而唯一记着它们
|
|
602
|
-
*
|
|
459
|
+
* 的表已经空了。
|
|
603
460
|
*
|
|
604
|
-
* ⚠️ 生产路径不是这条:宿主 `dispose()` 走 `OwnedProcessTable.release()
|
|
605
|
-
* `killAllTrackedProcesses()` 在生产路径上零调用方。
|
|
461
|
+
* ⚠️ 生产路径不是这条:宿主 `dispose()` 走 `OwnedProcessTable.release()`。
|
|
606
462
|
*
|
|
607
|
-
* 只清 `shell`
|
|
463
|
+
* 只清 `shell` 那一类:两族住在同一张表里,全清会顺手把别人的记录也带走。
|
|
608
464
|
*/
|
|
609
465
|
declare function clearAllShells(): void;
|
|
610
466
|
/**
|
|
@@ -612,16 +468,15 @@ declare function clearAllShells(): void;
|
|
|
612
468
|
*
|
|
613
469
|
* **两个触发点共用这一个函数**:{@link SHELL_SWEEP_MS} 那个定时器,以及每一次
|
|
614
470
|
* `shell_*` 调用(`sendToShell` / `readShell` / `listShells` 各自开头一句)。
|
|
615
|
-
*
|
|
616
|
-
*
|
|
617
|
-
*
|
|
471
|
+
* 两个都要:只有定时器的话用例得等真的墙上时钟;只有懒扫的话,模型不再碰 shell
|
|
472
|
+
* 工具时那几个 PTY 就活到进程退出 —— 而「10 分钟没动就收」是对**资源**的承诺,
|
|
473
|
+
* 不是对调用者的承诺。
|
|
618
474
|
*
|
|
619
475
|
* ⚠️ 扫的是 {@link allJobs}(跨会话),不是某个会话那一格:一个不再被打开的
|
|
620
|
-
* 会话里那几个 PTY
|
|
476
|
+
* 会话里那几个 PTY 恰恰是最该被收的。
|
|
621
477
|
*
|
|
622
|
-
* @param now
|
|
623
|
-
*
|
|
624
|
-
* 传一个未来的时刻,这条路的每一步都是真的。
|
|
478
|
+
* @param now 现在几点。**给用例留的口子**:真等 10 分钟的用例不可能存在,而假时钟
|
|
479
|
+
* 又验不到真进程被杀。传一个未来的时刻,这条路的每一步都是真的。
|
|
625
480
|
*/
|
|
626
481
|
declare function sweepIdleShells(now?: number): ShellInfo[];
|
|
627
482
|
|
|
@@ -662,55 +517,50 @@ declare function sweepIdleShells(now?: number): ShellInfo[];
|
|
|
662
517
|
declare function describeShell(info: ShellInfo): string;
|
|
663
518
|
|
|
664
519
|
/**
|
|
665
|
-
* 持久 shell
|
|
666
|
-
* `
|
|
520
|
+
* 持久 shell 会话那五个工具:`shell_open` / `shell_send` / `shell_read` /
|
|
521
|
+
* `shell_close` / `shell_list`。
|
|
667
522
|
*
|
|
668
|
-
* ## 为什么是新工具族,而不是给 `terminal`
|
|
523
|
+
* ## 为什么是新工具族,而不是给 `terminal` 加第四种模式
|
|
669
524
|
*
|
|
670
|
-
*
|
|
671
|
-
*
|
|
672
|
-
*
|
|
673
|
-
* 「我让它跑测试,它开了个后台任务然后说不知道结果」。
|
|
525
|
+
* `terminal` 已经有三种语义(管道 / PTY / 后台),它们的超时、输出上限、返回值、
|
|
526
|
+
* 审批口径各不相同;加持久就是第四种,工具描述会长成一张真值表 —— 而模型最容易
|
|
527
|
+
* 在这种工具上选错档,表现是「我让它跑测试,它开了个后台任务然后说不知道结果」。
|
|
674
528
|
*
|
|
675
529
|
* 名字用 `shell_*` 而不是 `terminal_*`:**`terminal` 这个名字已经是一个工具了**,
|
|
676
530
|
* `terminal_open` 和 `terminal` 并列会让模型以为前者是后者的一个模式。
|
|
677
531
|
*
|
|
678
532
|
* ## 权限:这一族里有两个真会执行命令
|
|
679
533
|
*
|
|
680
|
-
* | 工具
|
|
681
|
-
* |
|
|
682
|
-
* | `shell_open`
|
|
683
|
-
* | `shell_send`
|
|
684
|
-
* | `shell_read` / `shell_list` / `shell_close` | `file_read` |
|
|
534
|
+
* | 工具 | operation | 为什么 |
|
|
535
|
+
* | ------------------------------------------- | ----------- | ------------------------ |
|
|
536
|
+
* | `shell_open` | `command` | 它起一个进程 |
|
|
537
|
+
* | `shell_send` | `command` | **发进去的输入就是命令** |
|
|
538
|
+
* | `shell_read` / `shell_list` / `shell_close` | `file_read` | 不执行任何命令 |
|
|
685
539
|
*
|
|
686
540
|
* ⚠️ **`shell_send` 必须过危险命令表**,和 `terminal` 同一条。少了这一道,
|
|
687
541
|
* `shell_open` 之后一句 `shell_send({ input: 'rm -rf ~\n' })` 就是一条绕过护栏的
|
|
688
|
-
* 旁路 ——
|
|
542
|
+
* 旁路 —— 「后台不是旁路」那条既有判据(`tasks.ts` 文件头)说的是同一件事。
|
|
689
543
|
* 有用例守着。
|
|
690
544
|
*
|
|
691
|
-
* `shell_close` 归 `file_read` 而**不是** `command
|
|
692
|
-
*
|
|
693
|
-
*
|
|
694
|
-
* 「它拿不到任何新能力 + 类别就是授权单位,标成 `command` 等于把执行权发出去」。
|
|
695
|
-
* 完整的三条判据和「什么会让它翻过来」写在
|
|
696
|
-
* `core/src/permission/operation-type.ts` 的 `PROCESS_TABLE_TOOLS` 上,
|
|
545
|
+
* `shell_close` 归 `file_read` 而**不是** `command`:它拿不到任何新能力,而类别
|
|
546
|
+
* 就是授权单位,标成 `command` 等于把执行权发出去。三条判据和「什么会让它翻过来」
|
|
547
|
+
* 写在 `core/src/permission/operation-type.ts` 的 `PROCESS_TABLE_TOOLS` 上,
|
|
697
548
|
* `core/__tests__/job-control-permission.test.ts` 钉着它。
|
|
698
549
|
*
|
|
699
|
-
* ⚠️
|
|
700
|
-
*
|
|
701
|
-
* 就绕过一次确认框。那条一致性也在上面那个用例里。
|
|
550
|
+
* ⚠️ `task_stop s1` 和 `shell_close s1` 是**同一件事**(走同一个 `stopJob()`),
|
|
551
|
+
* 所以这两条的类别必须一致 —— 不一致的后果是模型换一个工具名就绕过一次确认框。
|
|
702
552
|
*
|
|
703
553
|
* ## 措辞分两处,判据在各自文件头
|
|
704
554
|
*
|
|
705
555
|
* 给模型读的输出在 [notice.ts](./notice.js)(整份进 i18n 的 `SKIP_FILES`)。
|
|
706
|
-
*
|
|
707
|
-
*
|
|
556
|
+
* 这个文件里的几条是**错误文案**:既进工具输出(模型读)、又以错误卡的形态印在
|
|
557
|
+
* TUI / Web 上,所以字仍在 catalog 里(`locales/{zh,en}.yaml` 的 `shell:` 一节,
|
|
708
558
|
* 不在这里硬编码一份英文)。
|
|
709
559
|
*
|
|
710
|
-
* ⚠️ **但渲染时一律显式传 `'en'
|
|
711
|
-
*
|
|
712
|
-
*
|
|
713
|
-
*
|
|
560
|
+
* ⚠️ **但渲染时一律显式传 `'en'`**:它们是 `error.message` / `error.suggestion`,
|
|
561
|
+
* 也就是**进工具输出的那一类**,而模型看到的东西不跟着界面语言走(判据同
|
|
562
|
+
* `core/src/code-mode/notice.ts` 的文件头)。catalog 里两份语言并列着,不是两次
|
|
563
|
+
* 书写 —— 同 `core/src/permission/by-level.ts` 的 `reasonPair()`。
|
|
714
564
|
*
|
|
715
565
|
* 剩下那些工具描述(`description`)本来就是英文,不在 i18n 的分母里,
|
|
716
566
|
* 而且它进 prompt 指纹 —— 跟着界面语言变才是错的。
|
|
@@ -781,10 +631,10 @@ declare const TASK_TOOLS: readonly EpochTool[];
|
|
|
781
631
|
* 参数 schema、危险命令拦截、workdir 边界、以及执行结果到 `ToolResult` 的映射。
|
|
782
632
|
*
|
|
783
633
|
* ⚠️ **另外两族工具的定义不在这个文件里**:四个 `task_*` 在
|
|
784
|
-
* [tasks.ts](./tasks.ts),五个 `shell_
|
|
634
|
+
* [tasks.ts](./tasks.ts),五个 `shell_*`(持久会话)在
|
|
785
635
|
* [shell/tools.ts](./shell/tools.ts)。这个文件只把它们摊进 `terminalPlugin.tools`。
|
|
786
|
-
* 分开的判据是**一个文件一族语义** ——
|
|
787
|
-
*
|
|
636
|
+
* 分开的判据是**一个文件一族语义** —— 三族的超时、上限、审批口径各不相同,挤在一起
|
|
637
|
+
* 读的人得先分辨每段注释在说哪一族。
|
|
788
638
|
*/
|
|
789
639
|
|
|
790
640
|
declare const terminalPlugin: EpochPlugin;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@epoch-agent/plugin-terminal",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.1.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "epoch-agent 终端命令执行插件",
|
|
6
6
|
"repository": {
|
|
@@ -22,8 +22,8 @@
|
|
|
22
22
|
],
|
|
23
23
|
"dependencies": {
|
|
24
24
|
"node-pty": "^1.1.0",
|
|
25
|
-
"@epoch-agent/
|
|
26
|
-
"@epoch-agent/
|
|
25
|
+
"@epoch-agent/protocol": "4.1.1",
|
|
26
|
+
"@epoch-agent/infra": "4.1.1"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@types/node": "^26.1.2",
|