@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 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
- ...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
  });
@@ -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: { ...process.env, TERM: "xterm-256color", FORCE_COLOR: "1" },
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.1.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.1.0",
26
- "@epoch-agent/protocol": "6.1.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",