@epoch-agent/plugin-terminal 6.2.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.
Files changed (3) hide show
  1. package/README.md +30 -0
  2. package/dist/index.js +34 -4
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -343,6 +343,7 @@ per-call 覆盖等于让「哪个 shell 在跑」有第二个说了算的地方
343
343
  | [`sandbox.ts`](src/sandbox.ts) | 把 argv 包进沙箱 + 算出要上报的东西。三条路共用 |
344
344
  | [`sandbox-notice.ts`](src/sandbox-notice.ts) | 把上面那份**说成给模型读的一行话** |
345
345
  | [`limits.ts`](src/limits.ts) | 输出上限和两句共用措辞。下沉成叶子,避开 import 环 |
346
+ | [`shell/env.ts`](src/shell/env.ts) | 子进程环境:什么时候把内置 rg 挂上 PATH |
346
347
 
347
348
  前两条路径在执行**期间**把每一块 stdout / stderr 交给 `ctx.onOutput`(宿主那边最终
348
349
  表现为 `tool-output-delta`)。后台路径没有「执行期间」可言——起完就返回 PID,一个字
@@ -382,6 +383,31 @@ SIGTERM → SIGKILL,但另外还有一个「发完 kill 最多再等多久就
382
383
  上限——处在不可中断睡眠的进程连 SIGKILL 都不理,不设上限的话用户按了 Esc 之后
383
384
  这次调用会永远挂着。
384
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
+
385
411
  ## 后台进程谁来收
386
412
 
387
413
  三条路径起的长期进程(后台命令、一次性 PTY、持久 shell 会话)**全部登记在
@@ -449,6 +475,10 @@ Windows 上给字符串、POSIX 上给数组。
449
475
 
450
476
  Windows 控制台的代码页解码也在 infra(`createStreamDecoder`)。
451
477
 
478
+ 子进程的 PATH 在 Windows 上认 `Path` / `PATH` 两种写法(见 `shell/env.ts` 的
479
+ `pathKey`):两种同时存在时只留一个 —— libuv 那个大小写不敏感的 `SetEnvironmentVariableW`
480
+ 谁最终生效取决于遍历顺序。
481
+
452
482
  ### 换 shell(只有 Windows 有这回事)
453
483
 
454
484
  配 `shell: powershell`(或 `pwsh`,见 [cli](../../cli) 的配置表)之后,这个插件
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
- ...sh.env ? { env: { ...process.env, ...sh.env } } : {}
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
- ...sh.env ? { env: { ...process.env, ...sh.env } } : {}
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: { ...process.env, TERM: "xterm-256color", FORCE_COLOR: "1" },
458
+ env: terminalEnv({ extra: { TERM: "xterm-256color", FORCE_COLOR: "1" } }),
429
459
  cols: 120,
430
460
  rows: 40
431
461
  });
@@ -729,7 +759,7 @@ async function openShell(sessionId, cwd, homeDir, sandbox) {
729
759
  pty = spawnPty2(sh.file, sh.args, {
730
760
  name: "xterm-256color",
731
761
  cwd,
732
- env: { ...process.env, TERM: "xterm-256color", FORCE_COLOR: "1" },
762
+ env: terminalEnv({ extra: { TERM: "xterm-256color", FORCE_COLOR: "1" } }),
733
763
  cols: 120,
734
764
  rows: 40
735
765
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@epoch-agent/plugin-terminal",
3
- "version": "6.2.0",
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.2.0",
26
- "@epoch-agent/protocol": "6.2.0"
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",