@epoch-agent/plugin-terminal 6.1.0 → 6.3.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/README.md +36 -0
- package/dist/index.d.ts +1 -16
- package/dist/index.js +48 -7
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -254,6 +254,12 @@ shell_list() → 看全部
|
|
|
254
254
|
shell_close({ id: 's1' }) → 关掉(杀整棵树)
|
|
255
255
|
```
|
|
256
256
|
|
|
257
|
+
⚠️ **`shell_open` 等 shell 打出第一段输出(提示符)再返回**(上限 250ms,见
|
|
258
|
+
`sessions.ts` 的 `READY_WAIT_MS`)。不等的话,紧接着的 `shell_send` 会落在两种
|
|
259
|
+
时序上:提示符先到 → 输入行被回显在提示符后面(`\x1b[?1034hsh-3.2$ pwd`);
|
|
260
|
+
输入先到 → 只有输入行本身。同一段输出两种形态,模型看到的世界就不确定,
|
|
261
|
+
评测录像也会因此「隔一次过期一次」。
|
|
262
|
+
|
|
257
263
|
`terminal` 三条路径**都是一次性的**,所以 `cd` 不留存、`source venv/bin/activate`
|
|
258
264
|
不留存、`export` 不留存、进了 REPL 就出不来 —— 这一族答的就是这个。
|
|
259
265
|
|
|
@@ -337,6 +343,7 @@ per-call 覆盖等于让「哪个 shell 在跑」有第二个说了算的地方
|
|
|
337
343
|
| [`sandbox.ts`](src/sandbox.ts) | 把 argv 包进沙箱 + 算出要上报的东西。三条路共用 |
|
|
338
344
|
| [`sandbox-notice.ts`](src/sandbox-notice.ts) | 把上面那份**说成给模型读的一行话** |
|
|
339
345
|
| [`limits.ts`](src/limits.ts) | 输出上限和两句共用措辞。下沉成叶子,避开 import 环 |
|
|
346
|
+
| [`shell/env.ts`](src/shell/env.ts) | 子进程环境:什么时候把内置 rg 挂上 PATH |
|
|
340
347
|
|
|
341
348
|
前两条路径在执行**期间**把每一块 stdout / stderr 交给 `ctx.onOutput`(宿主那边最终
|
|
342
349
|
表现为 `tool-output-delta`)。后台路径没有「执行期间」可言——起完就返回 PID,一个字
|
|
@@ -376,6 +383,31 @@ SIGTERM → SIGKILL,但另外还有一个「发完 kill 最多再等多久就
|
|
|
376
383
|
上限——处在不可中断睡眠的进程连 SIGKILL 都不理,不设上限的话用户按了 Esc 之后
|
|
377
384
|
这次调用会永远挂着。
|
|
378
385
|
|
|
386
|
+
## 子进程环境:模型敲的 `rg` 就是 `file_search` 那一份
|
|
387
|
+
|
|
388
|
+
四条起 shell 的路径(管道 / 后台 / 一次性 PTY / 持久会话)的环境都从
|
|
389
|
+
[`shell/env.ts`](src/shell/env.ts) 的 `terminalEnv()` 出。它在 **`resolveRipgrep()` 落到
|
|
390
|
+
`builtin` 档**时,把 vendor 包里那个 `bin/` 目录前置进子进程的 PATH —— 于是
|
|
391
|
+
`terminal({ command: 'rg -n TODO src' })` 用的就是内置 ripgrep,用户不必先
|
|
392
|
+
`brew install ripgrep`。
|
|
393
|
+
|
|
394
|
+
三条判据:
|
|
395
|
+
|
|
396
|
+
- **系统有 `rg` 就不挂**(`system` 档什么都不做)。用户自己装的那份通常比内置的新,
|
|
397
|
+
前置等于在 epoch 这个壳里悄悄把新版本换成旧的 —— 而他在自己的终端里体会不到
|
|
398
|
+
- **`not-executable` / `missing` 也不挂**:那个目录里要么没有能跑的文件、要么压根没有,
|
|
399
|
+
挂上去会让 `command -v rg` 说有、一敲就失败
|
|
400
|
+
- **只改这一份副本**:`process.env.PATH` 一个字节都不动。写进去的话,
|
|
401
|
+
`resolveRipgrep()` 的 `probeSystem()` 下次会看见我们自己挂的 `rg`,档位从 `builtin`
|
|
402
|
+
翻成 `system` —— 而它是进程级 memoize,于是解析结果取决于 terminal 有没有先跑过一次
|
|
403
|
+
|
|
404
|
+
⚠️ **这和 `verify-pack` 那条「vendor 包的 bin 不许叫 `rg`」不是一回事**:那条管的是
|
|
405
|
+
`node_modules/.bin/`(本地安装会提升到宿主工程根,盖掉宿主自己 npm 脚本里的 ripgrep),
|
|
406
|
+
这里管的是一个子进程的 PATH。两层别互相套用。
|
|
407
|
+
|
|
408
|
+
用例:[`__tests__/shell-env.test.ts`](__tests__/shell-env.test.ts)。其中一组是源码级断言 ——
|
|
409
|
+
四条路径任何一条把 `env` 内联回 `{ ...process.env }` 都会红。
|
|
410
|
+
|
|
379
411
|
## 后台进程谁来收
|
|
380
412
|
|
|
381
413
|
三条路径起的长期进程(后台命令、一次性 PTY、持久 shell 会话)**全部登记在
|
|
@@ -443,6 +475,10 @@ Windows 上给字符串、POSIX 上给数组。
|
|
|
443
475
|
|
|
444
476
|
Windows 控制台的代码页解码也在 infra(`createStreamDecoder`)。
|
|
445
477
|
|
|
478
|
+
子进程的 PATH 在 Windows 上认 `Path` / `PATH` 两种写法(见 `shell/env.ts` 的
|
|
479
|
+
`pathKey`):两种同时存在时只留一个 —— libuv 那个大小写不敏感的 `SetEnvironmentVariableW`
|
|
480
|
+
谁最终生效取决于遍历顺序。
|
|
481
|
+
|
|
446
482
|
### 换 shell(只有 Windows 有这回事)
|
|
447
483
|
|
|
448
484
|
配 `shell: powershell`(或 `pwsh`,见 [cli](../../cli) 的配置表)之后,这个插件
|
package/dist/index.d.ts
CHANGED
|
@@ -267,21 +267,6 @@ declare function clearAllTasks(): void;
|
|
|
267
267
|
/** 一行摘要,宿主展示用 */
|
|
268
268
|
declare function describeTask(info: BackgroundTaskInfo): string;
|
|
269
269
|
|
|
270
|
-
/**
|
|
271
|
-
* 持久 shell 会话的上限和契约类型(方案 49)。
|
|
272
|
-
*
|
|
273
|
-
* 单独一个文件的理由**和同包的 [../limits.ts](../limits.js) 逐字同款**:
|
|
274
|
-
* [sessions.ts](./sessions.js) 和 [notice.ts](./notice.js) 都要用它们,而那两个
|
|
275
|
-
* 文件之间不该为了几个常量互相 import —— 那会绕出一个
|
|
276
|
-
* `sessions → notice → sessions` 的环(会话表要用「写入失败」那句措辞,
|
|
277
|
-
* 措辞要用上限和状态类型)。常量和类型下沉成叶子,环就不存在了。
|
|
278
|
-
* `oxlint` 的 `import/no-cycle` 是 **error**,所以这不是风格问题。
|
|
279
|
-
*
|
|
280
|
-
* ## 四条上限的取值判据(方案 §1.3:不发明新数字,取值可以不同)
|
|
281
|
-
*
|
|
282
|
-
* 逐条对照后台任务那三条写在 [sessions.ts](./sessions.js) 的文件头,那里同时
|
|
283
|
-
* 交代了「为什么持久会话是 4 个而后台任务是 8 个」。
|
|
284
|
-
*/
|
|
285
270
|
/** **每个会话**同时最多开几个持久会话 */
|
|
286
271
|
declare const MAX_SHELLS = 4;
|
|
287
272
|
/** 单个会话留多少字节输出(环形,丢头保尾)。**真源在 infra 的 `JOB_OUTPUT_LIMIT`** */
|
|
@@ -416,7 +401,7 @@ interface ShellOpened {
|
|
|
416
401
|
* @param sandbox 这次的沙箱边界。**不传 = 不上沙箱**,如实标成 `not-requested`;
|
|
417
402
|
* 工具那条真实路径每次都传,且传的是**和 `terminal` 同一个** `sandboxPolicyFor()`
|
|
418
403
|
*/
|
|
419
|
-
declare function openShell(sessionId: string, cwd: string, homeDir?: string, sandbox?: SandboxPolicy): ShellOpened | ShellLimitReached | ShellSpawnFailed
|
|
404
|
+
declare function openShell(sessionId: string, cwd: string, homeDir?: string, sandbox?: SandboxPolicy): Promise<ShellOpened | ShellLimitReached | ShellSpawnFailed>;
|
|
420
405
|
interface ShellGone {
|
|
421
406
|
/** `undefined` = 压根没这个 id(或者是别的会话的) */
|
|
422
407
|
info?: ShellInfo;
|
package/dist/index.js
CHANGED
|
@@ -93,6 +93,36 @@ function confineShell(sh, policy, cwd) {
|
|
|
93
93
|
})
|
|
94
94
|
};
|
|
95
95
|
}
|
|
96
|
+
// src/shell/env.ts
|
|
97
|
+
import { posix, win32 } from "path";
|
|
98
|
+
import { resolveRipgrep } from "@epoch-agent/infra";
|
|
99
|
+
function terminalEnv(options = {}) {
|
|
100
|
+
const env = { ...options.base ?? process.env };
|
|
101
|
+
const platform2 = options.platform ?? process.platform;
|
|
102
|
+
const rgDir = builtinRgDir(options.resolution ?? resolveRipgrep(), platform2);
|
|
103
|
+
if (rgDir) prependPath(env, rgDir, platform2);
|
|
104
|
+
if (options.extra) Object.assign(env, options.extra);
|
|
105
|
+
return env;
|
|
106
|
+
}
|
|
107
|
+
function builtinRgDir(resolution, platform2) {
|
|
108
|
+
if (resolution.mode !== "builtin") return null;
|
|
109
|
+
const api = platform2 === "win32" ? win32 : posix;
|
|
110
|
+
if (!api.isAbsolute(resolution.command)) return null;
|
|
111
|
+
return api.dirname(resolution.command);
|
|
112
|
+
}
|
|
113
|
+
function prependPath(env, dir, platform2) {
|
|
114
|
+
const api = platform2 === "win32" ? win32 : posix;
|
|
115
|
+
const key = pathKey(env, platform2);
|
|
116
|
+
const current = env[key];
|
|
117
|
+
env[key] = current ? `${dir}${api.delimiter}${current}` : dir;
|
|
118
|
+
}
|
|
119
|
+
function pathKey(env, platform2) {
|
|
120
|
+
if (platform2 !== "win32") return "PATH";
|
|
121
|
+
const found = Object.keys(env).filter((k) => k.toUpperCase() === "PATH");
|
|
122
|
+
const key = found.includes("PATH") ? "PATH" : found[0] ?? "PATH";
|
|
123
|
+
for (const other of found) if (other !== key) delete env[other];
|
|
124
|
+
return key;
|
|
125
|
+
}
|
|
96
126
|
// src/background.ts
|
|
97
127
|
var MAX_TASKS = 8;
|
|
98
128
|
var MAX_TASK_OUTPUT = JOB_OUTPUT_LIMIT;
|
|
@@ -130,7 +160,7 @@ function startTask(sessionId, command, cwd, homeDir, sandbox) {
|
|
|
130
160
|
...cwd ? { cwd } : {},
|
|
131
161
|
spawnOptions: {
|
|
132
162
|
...sh.outcome.skipped === null ? { ...raw.options, windowsVerbatimArguments: false } : raw.options,
|
|
133
|
-
|
|
163
|
+
env: terminalEnv(sh.env ? { extra: sh.env } : {})
|
|
134
164
|
},
|
|
135
165
|
onOutput: (chunk) => job.append(chunk),
|
|
136
166
|
onExit: (code) => {
|
|
@@ -281,7 +311,7 @@ function runCommand(command, options) {
|
|
|
281
311
|
stdio: ["ignore", "pipe", "pipe"],
|
|
282
312
|
cwd: options.cwd,
|
|
283
313
|
...sh.outcome.skipped === null ? { ...raw.options, windowsVerbatimArguments: false } : raw.options,
|
|
284
|
-
|
|
314
|
+
env: terminalEnv(sh.env ? { extra: sh.env } : {})
|
|
285
315
|
}),
|
|
286
316
|
reject
|
|
287
317
|
);
|
|
@@ -425,7 +455,7 @@ function runCommandPty(command, options) {
|
|
|
425
455
|
pty = spawnPty(sh.file, sh.args, {
|
|
426
456
|
name: "xterm-256color",
|
|
427
457
|
cwd: options.cwd ?? process.cwd(),
|
|
428
|
-
env: {
|
|
458
|
+
env: terminalEnv({ extra: { TERM: "xterm-256color", FORCE_COLOR: "1" } }),
|
|
429
459
|
cols: 120,
|
|
430
460
|
rows: 40
|
|
431
461
|
});
|
|
@@ -553,6 +583,7 @@ import {
|
|
|
553
583
|
} from "@epoch-agent/infra";
|
|
554
584
|
// src/shell/limits.ts
|
|
555
585
|
import { JOB_OUTPUT_LIMIT as JOB_OUTPUT_LIMIT2 } from "@epoch-agent/infra";
|
|
586
|
+
var READY_WAIT_MS = 250;
|
|
556
587
|
var MAX_SHELLS = 4;
|
|
557
588
|
var MAX_SHELL_OUTPUT = JOB_OUTPUT_LIMIT2;
|
|
558
589
|
var MAX_SHELL_CHUNK = 8 * 1024;
|
|
@@ -711,7 +742,7 @@ function shellIn(sessionId, id) {
|
|
|
711
742
|
function toShellRead(read, detail) {
|
|
712
743
|
return { ...read, info: toShellInfo(read.info, detail) };
|
|
713
744
|
}
|
|
714
|
-
function openShell(sessionId, cwd, homeDir, sandbox) {
|
|
745
|
+
async function openShell(sessionId, cwd, homeDir, sandbox) {
|
|
715
746
|
const running = listJobs2(sessionId, "shell").filter((s) => s.status === "running");
|
|
716
747
|
if (running.length >= MAX_SHELLS) {
|
|
717
748
|
return {
|
|
@@ -728,7 +759,7 @@ function openShell(sessionId, cwd, homeDir, sandbox) {
|
|
|
728
759
|
pty = spawnPty2(sh.file, sh.args, {
|
|
729
760
|
name: "xterm-256color",
|
|
730
761
|
cwd,
|
|
731
|
-
env: {
|
|
762
|
+
env: terminalEnv({ extra: { TERM: "xterm-256color", FORCE_COLOR: "1" } }),
|
|
732
763
|
cols: 120,
|
|
733
764
|
rows: 40
|
|
734
765
|
});
|
|
@@ -763,10 +794,16 @@ function openShell(sessionId, cwd, homeDir, sandbox) {
|
|
|
763
794
|
job.setPid(pty.pid);
|
|
764
795
|
detail.untrack = processTableFor3(sessionId).trackForeign(pty.pid, () => killPtyTree(pty));
|
|
765
796
|
armSweep();
|
|
797
|
+
let markReady = () => {
|
|
798
|
+
};
|
|
799
|
+
const ready = new Promise((resolve3) => {
|
|
800
|
+
markReady = resolve3;
|
|
801
|
+
});
|
|
766
802
|
pty.onData((chunk) => {
|
|
767
803
|
if (detail.fresh) {
|
|
768
804
|
detail.fresh = false;
|
|
769
805
|
job.append(dropConPtyPreamble(chunk));
|
|
806
|
+
markReady();
|
|
770
807
|
return;
|
|
771
808
|
}
|
|
772
809
|
job.append(chunk);
|
|
@@ -775,6 +812,10 @@ function openShell(sessionId, cwd, homeDir, sandbox) {
|
|
|
775
812
|
job.finish("exited", exitCode);
|
|
776
813
|
afterEnd(detail);
|
|
777
814
|
});
|
|
815
|
+
const timeout = setTimeout(() => markReady(), READY_WAIT_MS);
|
|
816
|
+
timeout.unref?.();
|
|
817
|
+
await ready;
|
|
818
|
+
clearTimeout(timeout);
|
|
778
819
|
return { shell: toShellInfo(job.info(), detail), sandbox: sh.outcome };
|
|
779
820
|
}
|
|
780
821
|
function afterEnd(detail) {
|
|
@@ -936,7 +977,7 @@ var shellOpen = {
|
|
|
936
977
|
},
|
|
937
978
|
operation: "command",
|
|
938
979
|
describeTarget: (args) => String(args["workdir"] ?? ""),
|
|
939
|
-
execute: (args, ctx) => {
|
|
980
|
+
execute: async (args, ctx) => {
|
|
940
981
|
const workdir = args["workdir"] ? String(args["workdir"]) : void 0;
|
|
941
982
|
const baseDir = ctx.workDir || process.cwd();
|
|
942
983
|
const roots = [...ctx.extraRoots ?? [], ...ctx.grantedPaths ?? []];
|
|
@@ -950,7 +991,7 @@ var shellOpen = {
|
|
|
950
991
|
);
|
|
951
992
|
}
|
|
952
993
|
const cwd = workdir ? resolveWorkdir(workdir, baseDir) : baseDir;
|
|
953
|
-
const opened = openShell(ctx.sessionId, cwd, ctx.homeDir, sandboxPolicyFor(ctx, baseDir));
|
|
994
|
+
const opened = await openShell(ctx.sessionId, cwd, ctx.homeDir, sandboxPolicyFor(ctx, baseDir));
|
|
954
995
|
if ("error" in opened) {
|
|
955
996
|
if (opened.error === "limit") {
|
|
956
997
|
const list = opened.running.map(describeShell).join("\n");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@epoch-agent/plugin-terminal",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.3.0",
|
|
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/infra": "6.
|
|
26
|
-
"@epoch-agent/protocol": "6.
|
|
25
|
+
"@epoch-agent/infra": "6.3.0",
|
|
26
|
+
"@epoch-agent/protocol": "6.3.0"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@types/node": "^26.1.2",
|