@epoch-agent/plugin-terminal 3.2.0 → 4.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/README.md CHANGED
@@ -97,7 +97,11 @@
97
97
  第 1 条和第 3 条一个字都没变。那份清单也**不认上面那个开关**(它是一张静态的
98
98
  工具名清单)—— 开关关着时唯一如实说话的地方是每条命令自己的那一行回执。
99
99
  3. **Windows 上没有后端**,所以那儿一次都没包上 —— 工具输出里会逐字说
100
- 「本次没有 OS 级隔离」。`epoch doctor` 的沙箱一节印的是实测值。
100
+ `[sandbox: none] no OS-level isolation this time …`。`epoch doctor` 的沙箱一节印的是实测值。
101
+
102
+ > ⚠️ **工具输出(回给模型读的那一份)2026-11-05 起一律英文**,不跟用户界面语言走:
103
+ > 上面那行回执、截断与落盘提示、`task_*` / `shell_*` 的状态行、沙箱与失败说明都是。
104
+ > 判据同 `core/src/code-mode/notice.ts` 的文件头;工具 `description` 本来就是英文。
101
105
 
102
106
  PTY 那条是最后接的,而且方案里**允许的结论是「不上沙箱,如实说明」**:
103
107
  `sandbox-exec` 包一层之后 tty 分配 / 窗口尺寸 / 信号转发都可能坏,坏法还很阴
@@ -410,7 +414,7 @@ CLI / TUI / server 都是一进程一 runtime,碰不到;嵌入宿主要开
410
414
  命令是在一次性子 shell 里跑的,退出后 cwd 根本没变。所以检测到裸 `cd` 时,工具返回
411
415
  一条**准确**的提示:
412
416
 
413
- > `[提示] cd 只在本次子 shell 内生效,下次调用仍在原工作目录。若后续命令需要在 X 下执行,请传 workdir 参数,或写成 "cd X && <命令>"。`
417
+ > `[note] cd only takes effect inside this subshell; the next call still runs in the original working directory. If the following commands have to run in X, pass the workdir parameter, or write it as "cd X && <command>".`
414
418
 
415
419
  之前这里返回的是「[工作目录已切换: X]」——谎报会让模型基于错误的 cwd 假设继续拼
416
420
  相对路径。**这个插件不维护会话级工作目录。**
package/dist/index.d.ts CHANGED
@@ -651,6 +651,11 @@ declare function sweepIdleShells(now?: number): ShellInfo[];
651
651
  *
652
652
  * 三、**「活不过 epoch 进程」要在开会话的那一刻就说**。方案 §二 有一条 ⚠️
653
653
  * 逐字写着:不写的话模型会以为它能跨会话复用一个 venv。
654
+ *
655
+ * ## 2026-11-05 起措辞**一律英文**
656
+ *
657
+ * 上面那几条说的是「不进 catalog」;这一天又拍了一条:语言也不跟着用户界面走,
658
+ * 一律英文(判据同 `core/src/code-mode/notice.ts` 的文件头,跟工具 description 同一档)。
654
659
  */
655
660
 
656
661
  /** 一行摘要。五个工具和将来的展示层共用一份措辞(同 `describeTask`) */
@@ -697,10 +702,18 @@ declare function describeShell(info: ShellInfo): string;
697
702
  *
698
703
  * ## 措辞分两处,判据在各自文件头
699
704
  *
700
- * 给模型读的输出在 [notice.ts](./notice.js)(整份进 i18n 的 `SKIP_FILES`),
701
- * 用户可见的错误文案走 `t()`、key 在 `locales/{zh,en}.yaml` 的 `shell:` 一节。
702
- * 这个文件里因此**一个中文字面量都没有**,只有 `description`(工具描述给模型看,
703
- * 本来就不在 i18n 的分母里,而且它进 prompt 指纹 —— 跟着界面语言变才是错的)。
705
+ * 给模型读的输出在 [notice.ts](./notice.js)(整份进 i18n 的 `SKIP_FILES`)。
706
+ * 这个文件里的几条是**错误文案**:它们既进工具输出(模型读)、又以错误卡的形态
707
+ * 印在 TUI / Web 上,所以字仍然在 catalog 里(`locales/{zh,en}.yaml` 的 `shell:` 一节,
708
+ * 不在这里硬编码一份英文)。
709
+ *
710
+ * ⚠️ **但渲染时一律显式传 `'en'`**(2026-11-05):它们是 `error.message` /
711
+ * `error.suggestion`,也就是**进工具输出的那一类**,而模型看到的东西不跟着界面
712
+ * 语言走(判据同 `core/src/code-mode/notice.ts` 的文件头)。catalog 里两份语言
713
+ * 并列着,不是两次书写 —— 同 `core/src/permission/by-level.ts` 的 `reasonPair()`。
714
+ *
715
+ * 剩下那些工具描述(`description`)本来就是英文,不在 i18n 的分母里,
716
+ * 而且它进 prompt 指纹 —— 跟着界面语言变才是错的。
704
717
  */
705
718
 
706
719
  /**
package/dist/index.js CHANGED
@@ -94,9 +94,9 @@ var MAX_OUTPUT_CHUNK = 8 * 1024;
94
94
  function startTask(sessionId, command, cwd, homeDir, sandbox) {
95
95
  const running = listJobs(sessionId, "command").filter((j) => j.status === "running");
96
96
  if (running.length >= MAX_TASKS) {
97
- const list = running.map((j) => `${j.id} (${j.label})`).join("\u3001");
97
+ const list = running.map((j) => `${j.id} (${j.label})`).join(", ");
98
98
  return {
99
- error: `\u540E\u53F0\u4EFB\u52A1\u5DF2\u8FBE\u4E0A\u9650 ${MAX_TASKS} \u4E2A\uFF0C\u5148\u7528 task_stop \u505C\u6389\u4E00\u4E2A\u3002\u5728\u8DD1\u7684\uFF1A${list}`
99
+ error: `Too many background tasks (limit ${MAX_TASKS}); stop one with task_stop first. Running: ${list}`
100
100
  };
101
101
  }
102
102
  const raw = shellSpawnArgs(command);
@@ -194,9 +194,9 @@ function taskStatus(info) {
194
194
  function describeTask(info) {
195
195
  const dur = Math.round(((info.endedAt ?? Date.now()) - info.startedAt) / 1e3);
196
196
  const agent = info.kind === "agent";
197
- const state = info.status === "running" ? `\u8FD0\u884C\u4E2D ${dur}s` : info.status === "exited" ? agent ? "\u5DF2\u7ED3\u675F" : `\u5DF2\u7ED3\u675F\uFF0C\u9000\u51FA\u7801 ${info.exitCode}` : info.status === "killed" ? "\u5DF2\u505C\u6B62" : agent ? "\u5931\u8D25" : "\u542F\u52A8\u5931\u8D25";
198
- const trunc = info.truncated ? "\uFF0C\u5F00\u5934\u5DF2\u6EDA\u51FA\u7F13\u51B2" : "";
199
- return `${info.id} ${state}\uFF08${info.outputBytes} \u5B57\u8282\u8F93\u51FA${trunc}\uFF09 ${info.command ?? info.label}`;
197
+ const state = info.status === "running" ? `running ${dur}s` : info.status === "exited" ? agent ? "finished" : `finished, exit code ${info.exitCode}` : info.status === "killed" ? "stopped" : agent ? "failed" : "failed to start";
198
+ const trunc = info.truncated ? ", the start has scrolled out of the buffer" : "";
199
+ return `${info.id} ${state} (${info.outputBytes} bytes of output${trunc}) ${info.command ?? info.label}`;
200
200
  }
201
201
  // src/exec.ts
202
202
  import { spawn } from "child_process";
@@ -210,8 +210,8 @@ import {
210
210
  // src/limits.ts
211
211
  var MAX_CAPTURE_BYTES = 10 * 1024 * 1024;
212
212
  var OVER_CAPTURE_NOTICE = `
213
- [\u8F93\u51FA\u8D85\u8FC7 ${MAX_CAPTURE_BYTES / 1024 / 1024} MB\uFF0C\u5DF2\u622A\u65AD\u5E76\u7EC8\u6B62\u8FDB\u7A0B\uFF1A\u8FD9\u4E0D\u662F\u4E00\u6B21\u6B63\u5E38\u7684\u547D\u4EE4\u8F93\u51FA\uFF08\u591A\u534A\u662F cat \u4E86\u4E8C\u8FDB\u5236\u6587\u4EF6\u6216\u8FDB\u4E86\u6B7B\u5FAA\u73AF\uFF09\u3002\u8BF7\u7F29\u5C0F\u8F93\u51FA\u8303\u56F4\u91CD\u8BD5\uFF0C\u6BD4\u5982\u52A0 head / tail / grep\u3002]`;
214
- var NO_OUTPUT = "(\u65E0\u8F93\u51FA)";
213
+ [Output exceeded ${MAX_CAPTURE_BYTES / 1024 / 1024} MB and was truncated; the process was killed: this is not normal command output (most likely a binary file was cat'ed, or the command is stuck in a loop). Narrow the output and try again, e.g. with head / tail / grep.]`;
214
+ var NO_OUTPUT = "(no output)";
215
215
  // src/exec.ts
216
216
  var FORCE_SETTLE_MS = 3e3;
217
217
  function killChildTree(child) {
@@ -362,8 +362,8 @@ function ensurePtyHelperExecutable() {
362
362
  function ptyHelperHint() {
363
363
  if (failure === void 0) return "";
364
364
  return `
365
- node-pty \u7684 spawn-helper \u6CA1\u6709\u6267\u884C\u6743\u9650\uFF0C\u4E14\u81EA\u52A8\u4FEE\u590D\u5931\u8D25\uFF08${failure}\uFF09\u3002
366
- \u624B\u52A8\u4FEE\uFF1Achmod +x <\u4E0A\u9762\u8FD9\u4E2A\u8DEF\u5F84>`;
365
+ node-pty's spawn-helper is not executable and the automatic fix failed (${failure}).
366
+ Fix it by hand: chmod +x <the path above>`;
367
367
  }
368
368
  // src/pty.ts
369
369
  var PTY_IS_GROUP_LEADER = !IS_WINDOWS;
@@ -413,7 +413,7 @@ function runCommandPty(command, options) {
413
413
  });
414
414
  } catch (err) {
415
415
  resolve3({
416
- stdout: `PTY \u542F\u52A8\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}${ptyHelperHint()}`,
416
+ stdout: `PTY failed to start: ${err instanceof Error ? err.message : String(err)}${ptyHelperHint()}`,
417
417
  exitCode: 1,
418
418
  sandbox: sh.outcome
419
419
  });
@@ -440,7 +440,11 @@ function runCommandPty(command, options) {
440
440
  };
441
441
  const timer = setTimeout(() => {
442
442
  void killPtyTree(pty);
443
- finish({ stdout: output.trimEnd() || "(\u8D85\u65F6\uFF0C\u65E0\u8F93\u51FA)", exitCode: -1, sandbox: sh.outcome });
443
+ finish({
444
+ stdout: output.trimEnd() || "(timed out, no output)",
445
+ exitCode: -1,
446
+ sandbox: sh.outcome
447
+ });
444
448
  }, options.timeout);
445
449
  const abortCheck = setInterval(() => {
446
450
  if (!options.signal?.aborted) return;
@@ -477,43 +481,43 @@ function runCommandPty(command, options) {
477
481
  }
478
482
  // src/sandbox-notice.ts
479
483
  var MODE_BOUNDARY = {
480
- "read-only": "\u53EA\u8BFB\uFF1A\u5199\u4EFB\u4F55\u6587\u4EF6\u90FD\u4F1A\u88AB OS \u6321\u4E0B",
481
- "workspace-write": "\u5199\u5165\u9650\u4E8E\u5DE5\u4F5C\u533A\u3001\u4E34\u65F6\u76EE\u5F55\u548C\u5DE5\u5177\u94FE\u7F13\u5B58\uFF1B\u8BFB\u53D6\u548C\u7F51\u7EDC\u4E0D\u53D7\u9650",
482
- "danger-full-access": "\u4E0D\u8BBE\u9650"
484
+ "read-only": "read-only: any attempt to write a file is blocked by the OS",
485
+ "workspace-write": "writes are limited to the workspace, the temp directory and toolchain caches; reads and network are unrestricted",
486
+ "danger-full-access": "unrestricted"
483
487
  };
484
488
  function sandboxNotice(sb) {
485
489
  if (sb.skipped === "not-requested") return "";
486
490
  if (sb.skipped === "config-disabled") {
487
- return "[\u6C99\u7BB1: \u5173] \u914D\u7F6E\u91CC sandbox.terminal \u662F false\uFF0C\u672C\u6B21\u6CA1\u6709 OS \u7EA7\u9694\u79BB\uFF0C\u547D\u4EE4\u80FD\u8BFB\u5199\u6574\u4E2A\u6587\u4EF6\u7CFB\u7EDF\u3002\u8FD9\u4E00\u6863\u548C\u6743\u9650\u6863\u4F4D\u65E0\u5173\uFF08\u5BA1\u6279\u7167\u65E7\uFF09\uFF0C\u5371\u9669\u547D\u4EE4\u8868\u4ECD\u7136\u5728\u5C97\u3002";
491
+ return "[sandbox: off] sandbox.terminal is false in the config, so this run has no OS-level isolation and the command can read and write the whole filesystem. This tier is unrelated to the permission level (approvals still apply), and the dangerous-command table is still in place.";
488
492
  }
489
493
  if (sb.skipped === "mode-disabled") {
490
- return "[\u6C99\u7BB1: \u5173] \u5F53\u524D\u6743\u9650\u6863\u4F4D\uFF08`auto` / `bypass` \u4E24\u6863\u90FD\u4E0D\u4E0A\u6C99\u7BB1\uFF09\uFF0C\u672C\u6B21\u6CA1\u6709 OS \u7EA7\u9694\u79BB\u3002\u5371\u9669\u547D\u4EE4\u8868\u4ECD\u7136\u5728\u5C97\u3002";
494
+ return "[sandbox: off] the current permission level (`auto` / `bypass` \u2014 neither applies a sandbox), so this run has no OS-level isolation. The dangerous-command table is still in place.";
491
495
  }
492
496
  if (sb.skipped === "no-backend") {
493
- return `[\u6C99\u7BB1: \u65E0] \u672C\u6B21\u6CA1\u6709 OS \u7EA7\u9694\u79BB\u2014\u2014\u8FD9\u4E2A\u5E73\u53F0\uFF08${sb.backend === "none" ? process.platform : sb.backend}\uFF09\u4E0A\u63A2\u6D4B\u4E0D\u5230\u53EF\u7528\u540E\u7AEF\uFF0C\u547D\u4EE4\u80FD\u8BFB\u5199\u6574\u4E2A\u6587\u4EF6\u7CFB\u7EDF\u3002`;
497
+ return `[sandbox: none] no OS-level isolation this time \u2014 no usable backend was detected on this platform (${sb.backend === "none" ? process.platform : sb.backend}), so the command can read and write the whole filesystem.`;
494
498
  }
495
499
  if (sb.skipped === "escalated") {
496
- return "[\u6C99\u7BB1: \u5173] \u8FD9\u4E00\u6B21\u662F\u6A21\u578B\u8BF7\u6C42\u653E\u5F00\u8FB9\u754C\u3001\u7528\u6237\u5355\u72EC\u6279\u51C6\u4E4B\u540E\u6267\u884C\u7684\uFF0C\u6CA1\u6709 OS \u7EA7\u9694\u79BB\u3002\u53EA\u5BF9\u8FD9\u4E00\u6B21\u8C03\u7528\u751F\u6548\uFF0C\u4E0B\u4E00\u4E2A\u5DE5\u5177\u8C03\u7528\u91CD\u65B0\u6309\u6863\u4F4D\u5305\u3002\u5371\u9669\u547D\u4EE4\u8868\u4ECD\u7136\u5728\u5C97\u3002";
500
+ return "[sandbox: off] this run was executed after the model requested a wider boundary and the user approved it separately, so there is no OS-level isolation. It applies to this call only \u2014 the next tool call is confined again according to the tier. The dangerous-command table is still in place.";
497
501
  }
498
502
  const boundary = MODE_BOUNDARY[sb.mode ?? ""] ?? "";
499
503
  if (sb.enforcement === "partial") {
500
- return `[\u6C99\u7BB1: ${sb.backend} \xB7 ${sb.mode} \xB7 \u5F3A\u5236\u4E0D\u5B8C\u6574] ${boundary}\u3002\u4E0D\u5B8C\u6574\u4E4B\u5904\uFF1APOSIX shell \u5FC5\u987B\u7559\u7740 /dev/null \u8FD9\u4E2A\u5199\u5165\u53E3\uFF0C\u5426\u5219\u5B83\u81EA\u5DF1\u90FD\u8D77\u4E0D\u6765\u3002`;
504
+ return `[sandbox: ${sb.backend} \xB7 ${sb.mode} \xB7 enforcement incomplete] ${boundary}. What is incomplete: the POSIX shell has to keep /dev/null writable, otherwise it cannot even start.`;
501
505
  }
502
- return `[\u6C99\u7BB1: ${sb.backend} \xB7 ${sb.mode}] ${boundary}\u3002`;
506
+ return `[sandbox: ${sb.backend} \xB7 ${sb.mode}] ${boundary}.`;
503
507
  }
504
508
  function sandboxError(sb) {
505
509
  const failure2 = sb.failure;
506
510
  if (!failure2) return null;
507
511
  if (failure2.kind === "runner-failed") {
508
512
  return {
509
- message: `\u6C99\u7BB1\u542F\u52A8\u5931\u8D25\uFF0C\u547D\u4EE4\u6CA1\u6709\u6267\u884C\uFF1A${failure2.evidence ?? "(\u6C99\u7BB1\u672A\u7ED9\u51FA\u539F\u56E0)"}`,
510
- suggestion: "\u8FD9\u4E0D\u662F\u547D\u4EE4\u672C\u8EAB\u7684\u95EE\u9898\uFF0C\u522B\u6539\u547D\u4EE4\uFF0C\u4E5F\u522B\u529D\u4ED6\u5207\u300C\u5141\u8BB8\u4E00\u5207\u300D\u6863\u4F4D\uFF08\u90A3\u8FDE\u5BA1\u6279\u4E00\u8D77\u653E\u5F00\uFF09\u3002\u6700\u8F7B\u7684\u51FA\u8DEF\u662F\u8BF7\u7528\u6237\u5728\u4ED6\u81EA\u5DF1\u7684\u7EC8\u7AEF\u91CC\u8DD1\u8FD9\u4E00\u904D\u3001\u628A\u7ED3\u679C\u8D34\u56DE\u6765\u3002\u8981\u5F7B\u5E95\u7ED5\u5F00\uFF0C\u53EA\u6709 `epoch config set sandbox.terminal false`\uFF08\u5373 config.yaml \u91CC\u7684 `sandbox.terminal: false`\uFF09\u2014\u2014 \u5168\u5C40\u5F00\u5173\uFF08\u53EA\u5173\u6C99\u7BB1\u3001\u5BA1\u6279\u4E0D\u52A8\uFF09\uFF0C\u6539\u5B8C\u8981\u91CD\u542F epoch \u624D\u751F\u6548\uFF0C\u65B0\u5F00\u4F1A\u8BDD\u4E0D\u591F\u3002"
513
+ message: `The sandbox failed to start and the command was not executed: ${failure2.evidence ?? "(the sandbox gave no reason)"}`,
514
+ suggestion: 'This is not a problem with the command \u2014 do not rewrite it, and do not talk the user into the "allow everything" tier (that opens approvals up as well). The cheapest way out is to ask the user to run it once in their own terminal and paste the result back. To bypass it entirely there is only `epoch config set sandbox.terminal false` (i.e. `sandbox.terminal: false` in config.yaml) \u2014 a global switch (it turns the sandbox off and leaves approvals alone), and it needs an epoch restart to take effect; opening a new session is not enough.'
511
515
  };
512
516
  }
513
517
  if (failure2.kind === "sandbox-denied") {
514
518
  return {
515
- message: `\u547D\u4EE4\u88AB\u6C99\u7BB1\u6321\u4E0B\uFF1A${failure2.evidence ?? "(\u6C99\u7BB1\u672A\u7ED9\u51FA\u539F\u56E0)"}`,
516
- suggestion: sb.mode === "read-only" ? "\u5F53\u524D\u662F plan \u6863\uFF08\u53EA\u8BFB\uFF09\uFF0C\u4EFB\u4F55\u5199\u5165\u90FD\u4F1A\u88AB\u6321 \u2014\u2014 \u8FD9\u662F plan \u6A21\u5F0F\u7684\u627F\u8BFA\uFF0C\u4E0D\u662F\u914D\u7F6E\u51FA\u4E86\u95EE\u9898\u3002\u540C\u4E00\u6761\u8FB9\u754C\u4E0B\u6362\u4E2A\u5199\u6CD5\u8FD8\u662F\u4F1A\u88AB\u6321\uFF0C\u522B\u53CD\u590D\u8BD5\u3002\u8981\u771F\u7684\u6539\u4E1C\u897F\uFF0C\u8BF7\u7528\u6237\u5207\u51FA plan \u6863\uFF08\u5207\u5B8C\u7ACB\u523B\u751F\u6548\u3001\u53EF\u9006\uFF09\uFF1B\u4ED6\u4E0D\u5728\u65C1\u8FB9\u65F6\uFF0C\u4E5F\u53EF\u4EE5\u8BF7\u4ED6\u81EA\u5DF1\u628A\u8FD9\u6761\u547D\u4EE4\u8DD1\u4E00\u904D\u3002" : '\u6C99\u7BB1\u53EA\u653E\u5F00\u5DE5\u4F5C\u533A\u3001\u4E34\u65F6\u76EE\u5F55\u548C\u5DE5\u5177\u94FE\u7F13\u5B58 \u2014\u2014 \u540C\u4E00\u6761\u8FB9\u754C\u4E0B\u6362\u4E2A\u5199\u6CD5\u8FD8\u662F\u4F1A\u88AB\u6321\uFF0C\u522B\u53CD\u590D\u8BD5\u3002\u6309\u4EE3\u4EF7\u4ECE\u8F7B\u5230\u91CD\u6311\u4E00\u6761\u8BF7\u7528\u6237\u529E\uFF1A\u2460 \u5982\u679C\u4F60\u786E\u8BA4\u8FD9\u4E00\u6B21\u5FC5\u987B\u8D8A\u754C\uFF0C\u5E26\u4E0A `sandbox_permissions: "danger-full-access"` \u548C `justification`\uFF08\u4E00\u53E5\u8BDD\u8BF4\u660E\u4E3A\u4EC0\u4E48\u5FC5\u987B\u8D8A\u754C\uFF09**\u518D\u8C03\u4E00\u6B21** \u2014\u2014 \u7528\u6237\u4F1A\u5355\u72EC\u6536\u5230\u4E00\u6B21\u5347\u6743\u5BA1\u6279\uFF0C\u6279\u4E86\u5C31\u53EA\u6709\u8FD9\u4E00\u6B21\u4E0D\u5305\u6C99\u7BB1\uFF0C\u4E0B\u4E00\u6761\u547D\u4EE4\u7167\u65E7\uFF1B\u2461 \u4ED6\u5728\u81EA\u5DF1\u7684\u7EC8\u7AEF\u91CC\u8DD1\u8FD9\u4E00\u904D\u3001\u628A\u7ED3\u679C\u8D34\u56DE\u6765\uFF08\u96F6\u964D\u7EA7\uFF09\uFF1B\u2462 \u628A\u8981\u5199\u7684\u76EE\u6807\u632A\u8FDB\u5DE5\u4F5C\u533A\uFF1B\u2463 \u786E\u5B9E\u9700\u8981\u6574\u4E2A\u4F1A\u8BDD\u653E\u5F00\u8FB9\u754C\uFF0C\u624D\u8BF7\u4ED6\u5207\u5230 auto \u6863\uFF08\u90A3\u4E00\u6863\u6CA1\u6709 OS \u6C99\u7BB1\uFF0C\u53EA\u5269\u5371\u9669\u547D\u4EE4\u8868\uFF1B\u53EF\u9006\u3001\u7ACB\u523B\u751F\u6548\uFF09\uFF1B\u2464 \u53EA\u6709\u5F53\u88AB\u6321\u7684\u662F\u4E00\u6761\u672C\u6765\u8BE5\u80FD\u8DD1\u7684\u547D\u4EE4\uFF08\u6BD4\u5982\u67D0\u4E2A\u6CA1\u767B\u8BB0\u7684\u7F13\u5B58\u76EE\u5F55\uFF09\uFF0C\u624D\u52A8 `epoch config set sandbox.terminal false`\uFF08\u5373 config.yaml \u91CC\u7684 `sandbox.terminal: false`\uFF09\u2014\u2014 \u5168\u5C40\u5F00\u5173\uFF0C\u6539\u5B8C\u8981\u91CD\u542F epoch \u624D\u751F\u6548\uFF08\u65B0\u5F00\u4F1A\u8BDD\u4E0D\u591F\uFF09\uFF0C\u6539\u56DE\u53BB\u4E5F\u8981\u518D\u91CD\u542F\u4E00\u6B21\u3002'
519
+ message: `Command blocked by the sandbox: ${failure2.evidence ?? "(the sandbox gave no reason)"}`,
520
+ suggestion: sb.mode === "read-only" ? "The current tier is plan (read-only), so any write is blocked \u2014 that is plan mode keeping its promise, not a broken config. Rewriting it inside the same boundary will still be blocked, so do not keep retrying. To actually change something, ask the user to leave plan mode (it takes effect immediately and is reversible); if they are not around, you can also ask them to run this command themselves." : 'The sandbox only allows the workspace, the temp directory and toolchain caches \u2014 rewriting it inside the same boundary will still be blocked, so do not keep retrying. Pick one of these, cheapest first, and let the user handle it: (1) if you are sure this one call has to cross the boundary, pass `sandbox_permissions: "danger-full-access"` together with `justification` (one sentence on why it must) and **call again** \u2014 the user gets a separate escalation approval, and if they approve it only this one call runs unconfined, the next command is confined as usual; (2) have them run it once in their own terminal and paste the result back (zero downgrade); (3) move whatever you need to write into the workspace; (4) only if the whole session really needs the boundary lifted, ask them to switch to the auto tier (that one has no OS sandbox, only the dangerous-command table; reversible, takes effect immediately); (5) only when the blocked command is one that should have worked (say, an unregistered cache directory), touch `epoch config set sandbox.terminal false` (i.e. `sandbox.terminal: false` in config.yaml) \u2014 a global switch that needs an epoch restart to take effect (opening a new session is not enough), and switching it back needs another restart.'
517
521
  };
518
522
  }
519
523
  return null;
@@ -546,10 +550,10 @@ function formatBytes(text) {
546
550
  function retrievalHint(locator) {
547
551
  return `
548
552
 
549
- \u5B8C\u6574\u8F93\u51FA\u5DF2\u4FDD\u5B58\uFF1A${locator}
550
- \u53D6\u56DE\u65B9\u5F0F\uFF1A\u7528 file_search \u5728\u8FD9\u4E2A\u8DEF\u5F84\u91CC\u641C\u4F60\u8981\u7684\u5185\u5BB9\uFF08\u6BD4\u5982\u62A5\u9519\u5173\u952E\u5B57\uFF09\uFF0C\u6216\u7528 file_read \u5206\u9875\u8BFB\u3002`;
553
+ Full output saved to: ${locator}
554
+ To get it back, search that path with file_search (e.g. for the error keyword), or page through it with file_read.`;
551
555
  }
552
- var NOT_STORED = "\n\n\uFF08\u8FD9\u6B21\u6CA1\u80FD\u4FDD\u5B58\u5B8C\u6574\u8F93\u51FA\uFF0C\u88AB\u7701\u7565\u7684\u90E8\u5206\u5DF2\u7ECF\u6CA1\u6709\u4E86\uFF09";
556
+ var NOT_STORED = "\n\n(Could not save the full output this time; the omitted part is gone)";
553
557
  function spillOutput(input) {
554
558
  const { full, sessionId, homeDir, label, mode } = input;
555
559
  if (full.length <= SPILL_THRESHOLD) return { text: full };
@@ -558,9 +562,9 @@ function spillOutput(input) {
558
562
  const tail = tailCodePoints(full, PREVIEW_TAIL);
559
563
  const skipped = full.slice(head.length, full.length - tail.length);
560
564
  if (skipped.length === 0) return { text: full, ...locator ? { locator } : {} };
561
- const body = `[\u8F93\u51FA ${formatBytes(full)}\uFF0C\u4E0B\u9762\u53EA\u662F\u9884\u89C8]
565
+ const body = `[Output is ${formatBytes(full)}; what follows is only a preview]
562
566
  ${head ? `${head}
563
- ` : ""}\u2026[\u7701\u7565 ${formatBytes(skipped)}]\u2026
567
+ ` : ""}\u2026[${formatBytes(skipped)} omitted]\u2026
564
568
  ${tail}`;
565
569
  return {
566
570
  text: body + (locator ? retrievalHint(locator) : NOT_STORED),
@@ -569,10 +573,10 @@ ${tail}`;
569
573
  }
570
574
  function describeMissed(missed, locator) {
571
575
  const where = locator ? retrievalHint(locator) : NOT_STORED;
572
- return `\uFF08\u5F00\u5934 ${missed} \u5B57\u8282\u5DF2\u7ECF\u6EDA\u51FA\u73AF\u5F62\u7F13\u51B2\uFF09${where}`;
576
+ return `(the first ${missed} bytes have scrolled out of the ring buffer)${where}`;
573
577
  }
574
578
  function describeMore(nextCursor) {
575
- return `\uFF08\u8FD8\u6709\u66F4\u591A\uFF0C\u7528 since: ${nextCursor} \u7EE7\u7EED\u53D6\uFF09`;
579
+ return `(more remains \u2014 continue with since: ${nextCursor})`;
576
580
  }
577
581
  // src/shell/notice.ts
578
582
  function stateOf(info) {
@@ -580,41 +584,41 @@ function stateOf(info) {
580
584
  switch (info.status) {
581
585
  case "running": {
582
586
  const idle = Math.round((Date.now() - info.lastActivity) / 1e3);
583
- return `\u6D3B\u7740 ${alive}s\uFF08\u7A7A\u95F2 ${idle}s\uFF09`;
587
+ return `alive ${alive}s (idle ${idle}s)`;
584
588
  }
585
589
  case "exited":
586
- return `shell \u81EA\u5DF1\u9000\u4E86\uFF0C\u9000\u51FA\u7801 ${info.exitCode}`;
590
+ return `the shell exited on its own, exit code ${info.exitCode}`;
587
591
  case "closed":
588
- return "\u5DF2\u5173\u95ED";
592
+ return "closed";
589
593
  case "reaped":
590
- return `\u7A7A\u95F2\u8D85\u8FC7 ${SHELL_IDLE_MS / 6e4} \u5206\u949F\uFF0C\u5DF2\u56DE\u6536`;
594
+ return `idle for more than ${SHELL_IDLE_MS / 6e4} minutes, reclaimed`;
591
595
  }
592
596
  }
593
597
  function describeShell(info) {
594
- const trunc = info.truncated ? "\uFF0C\u5F00\u5934\u5DF2\u6EDA\u51FA\u7F13\u51B2" : "";
595
- return `${info.id} ${stateOf(info)} cwd=${info.cwd}\uFF08${info.outputBytes} \u5B57\u8282\u8F93\u51FA${trunc}\uFF09`;
598
+ const trunc = info.truncated ? ", the start has scrolled out of the buffer" : "";
599
+ return `${info.id} ${stateOf(info)} cwd=${info.cwd} (${info.outputBytes} bytes of output${trunc})`;
596
600
  }
597
601
  function openedNotice(info) {
598
602
  return [
599
- `\u6301\u4E45 shell \u4F1A\u8BDD ${info.id} \u5DF2\u5F00\uFF1A${info.shell}\uFF0C\u5DE5\u4F5C\u76EE\u5F55 ${info.cwd}`,
600
- "shell_send \u53D1\u8F93\u5165\uFF08\u8BB0\u5F97\u81EA\u5DF1\u5E26 \\n\uFF09\xB7 shell_read \u589E\u91CF\u8BFB \xB7 shell_close \u5173\u6389 \xB7 shell_list \u770B\u5168\u90E8\u3002",
601
- `\u6CE8\u610F\uFF1A\u4F1A\u8BDD\u6D3B\u4E0D\u8FC7 epoch \u8FDB\u7A0B\uFF0C\u9000\u51FA\u65F6\u4F1A\u88AB\u4E00\u8D77\u6536\u6389\uFF1B\u7A7A\u95F2 ${SHELL_IDLE_MS / 6e4} \u5206\u949F\u4E5F\u4F1A\u88AB\u56DE\u6536\u3002`
603
+ `Persistent shell session ${info.id} opened: ${info.shell}, working directory ${info.cwd}`,
604
+ "shell_send sends input (include the \\n yourself) \xB7 shell_read reads incrementally \xB7 shell_close closes it \xB7 shell_list lists them all.",
605
+ `Note: the session does not outlive the epoch process \u2014 it is collected when epoch exits, and it is also reclaimed after ${SHELL_IDLE_MS / 6e4} minutes idle.`
602
606
  ].join("\n");
603
607
  }
604
608
  function closedNotice(id) {
605
- return `${id} \u5DF2\u5173\u95ED\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002`;
609
+ return `${id} closed (along with any processes it started).`;
606
610
  }
607
611
  function alreadyGoneNotice(id) {
608
- return `${id} \u5DF2\u7ECF\u4E0D\u5728\u8FD0\u884C\u4E2D\u4E86\u3002`;
612
+ return `${id} is no longer running.`;
609
613
  }
610
- var NO_SHELLS = "\u6CA1\u6709\u6301\u4E45 shell \u4F1A\u8BDD\u3002\u7528 shell_open \u5F00\u4E00\u4E2A\u3002";
614
+ var NO_SHELLS = "No persistent shell sessions. Open one with shell_open.";
611
615
  function listHead(count) {
612
- return `${count} \u4E2A\u6301\u4E45 shell \u4F1A\u8BDD\uFF08\u540C\u65F6\u6700\u591A ${MAX_SHELLS} \u4E2A\uFF09`;
616
+ return `${count} persistent shell session(s) (at most ${MAX_SHELLS} at a time)`;
613
617
  }
614
- var NO_NEW_OUTPUT = "\uFF08\u8FD9\u4E00\u6BB5\u6CA1\u6709\u65B0\u8F93\u51FA\u3002\u547D\u4EE4\u53EF\u80FD\u8FD8\u5728\u8DD1\uFF0C\u7B49\u4E00\u4F1A\u513F\u518D shell_read\uFF09";
618
+ var NO_NEW_OUTPUT = "(no new output in this range. The command may still be running \u2014 shell_read again in a moment)";
615
619
  function writeFailedNotice(message) {
616
620
  return `
617
- [\u5199\u5165\u5931\u8D25\uFF1A${message}]
621
+ [write failed: ${message}]
618
622
  `;
619
623
  }
620
624
  function readNotice(result) {
@@ -851,17 +855,25 @@ function fail(code, message, suggestion) {
851
855
  };
852
856
  }
853
857
  function notFound(id) {
854
- return fail(2101, t("shell.not_found", { id }), t("shell.not_found_suggestion"));
858
+ return fail(
859
+ 2101,
860
+ t("shell.not_found", { id }, "en"),
861
+ t("shell.not_found_suggestion", void 0, "en")
862
+ );
855
863
  }
856
864
  function notRunning(info) {
857
865
  if (info.status === "reaped") {
858
866
  return fail(
859
867
  2102,
860
- t("shell.reaped", { id: info.id, minutes: SHELL_IDLE_MS / 6e4 }),
861
- t("shell.reaped_suggestion")
868
+ t("shell.reaped", { id: info.id, minutes: SHELL_IDLE_MS / 6e4 }, "en"),
869
+ t("shell.reaped_suggestion", void 0, "en")
862
870
  );
863
871
  }
864
- return fail(2102, t("shell.not_running", { id: info.id }), t("shell.not_running_suggestion"));
872
+ return fail(
873
+ 2102,
874
+ t("shell.not_running", { id: info.id }, "en"),
875
+ t("shell.not_running_suggestion", void 0, "en")
876
+ );
865
877
  }
866
878
  function toolResultFor(id, result, ctx) {
867
879
  if (!("output" in result)) {
@@ -876,22 +888,22 @@ ${sbErr.suggestion}` : body);
876
888
  }
877
889
  var shellOpen = {
878
890
  name: "shell_open",
879
- description: `\u5F00\u4E00\u4E2A**\u6301\u4E45** shell \u4F1A\u8BDD\uFF08PTY\uFF09\uFF0C\u8FD4\u56DE\u4F1A\u8BDD id\u3002\u548C terminal \u7684\u533A\u522B\u662F\u5B83\u8DE8\u591A\u6B21\u5DE5\u5177\u8C03\u7528\u6D3B\u7740\uFF1Acd / export / source venv/bin/activate \u90FD\u4F1A\u7559\u5B58\uFF0CREPL \u8FDB\u53BB\u4E86\u8FD8\u80FD\u51FA\u6765\u3002\u9002\u5408\u300C\u5148\u6FC0\u6D3B\u73AF\u5883\u518D\u8DD1\u51E0\u6761\u547D\u4EE4\u300D\u300C\u591A\u8F6E\u4EA4\u4E92\u7684 npm init\u300D\u300CNode / Python REPL\u300D\u3002\u540C\u65F6\u6700\u591A ${MAX_SHELLS} \u4E2A\uFF1B\u7A7A\u95F2 ${SHELL_IDLE_MS / 6e4} \u5206\u949F\u4F1A\u88AB\u56DE\u6536\uFF1B**\u4F1A\u8BDD\u6D3B\u4E0D\u8FC7 epoch \u8FDB\u7A0B**\uFF08\u9000\u51FA\u65F6\u4E00\u8D77\u6536\u6389\uFF0C\u522B\u6307\u671B\u4E0B\u6B21\u8FD0\u884C\u8FD8\u5728\uFF09\u3002\u4E00\u6B21\u6027\u547D\u4EE4\u4ECD\u7136\u7528 terminal \u2014\u2014 \u90A3\u6761\u4E0D\u5FC5\u5F00\u4F1A\u8BDD\u3002`,
891
+ description: `Open a **persistent** shell session (PTY) and return its id. Unlike terminal, it survives across tool calls: cd / export / source venv/bin/activate all persist, and a REPL stays open. Use it for work that needs state between commands; use terminal for one-off commands. At most ${MAX_SHELLS} sessions can be open at once, one idle for ${SHELL_IDLE_MS / 6e4} minutes is reclaimed, and none outlive the epoch process.`,
880
892
  parameters: {
881
893
  type: "object",
882
894
  properties: {
883
895
  workdir: {
884
896
  type: "string",
885
- description: "\u4F1A\u8BDD\u7684\u521D\u59CB\u5DE5\u4F5C\u76EE\u5F55\uFF08\u5FC5\u987B\u5728\u5DE5\u4F5C\u533A\u5185\uFF0C\u76F8\u5BF9\u8DEF\u5F84\u6309\u5DE5\u4F5C\u533A\u6839\u89E3\u6790\uFF09"
897
+ description: "Initial working directory for the session. Must be inside the workspace; a relative path is resolved against the workspace root."
886
898
  },
887
899
  [SANDBOX_PERMISSIONS_PARAM]: {
888
900
  type: "string",
889
901
  enum: [...ESCALATION_TARGETS],
890
- description: "\u4EC5\u5F53\u4E0A\u4E00\u8F6E\u4F1A\u8BDD\u88AB\u6C99\u7BB1\u6321\u4E0B\u3001\u4E14\u786E\u8BA4\u6574\u4E2A\u4F1A\u8BDD\u90FD\u9700\u8981\u8D8A\u754C\u65F6\u624D\u7528\uFF1A\u8BF7\u6C42\u653E\u5F00**\u8FD9\u4E2A\u4F1A\u8BDD**\u7684\u6C99\u7BB1\u8FB9\u754C\u3002\u26A0\uFE0F \u548C terminal \u7684\u4E0D\u540C\uFF1A\u5B83\u7BA1\u7684\u662F\u6574\u4E2A\u4F1A\u8BDD\uFF08\u4E4B\u540E\u6240\u6709 shell_send\uFF09\uFF0C\u4E0D\u662F\u4E00\u4E2A\u547D\u4EE4\u3002\u53D6\u503C\u53EA\u80FD\u662F\u5F53\u524D\u6863\u4F4D\u4E25\u683C\u66F4\u5BBD\u7684\u90A3\u4E00\u9879\uFF0C\u4E14\u5FC5\u987B\u548C justification \u6210\u5BF9\u51FA\u73B0\u3002\u7528\u6237\u4F1A\u5355\u72EC\u770B\u5230\u4E00\u6B21\u5347\u6743\u5BA1\u6279\u3002"
902
+ description: "Only when the previous attempt was stopped by the sandbox and the whole session needs to cross the boundary: request a wider sandbox for **this session**. Unlike terminal, this covers the entire session (every later shell_send), not one command. The value must be strictly wider than the current tier, and it must come with justification. The user sees a separate escalation request."
891
903
  },
892
904
  [JUSTIFICATION_PARAM]: {
893
905
  type: "string",
894
- description: "\u4E00\u53E5\u8BDD\u8BF4\u660E\u4E3A\u4EC0\u4E48\u6574\u4E2A\u4F1A\u8BDD\u90FD\u5FC5\u987B\u8D8A\u754C\uFF0C\u7ED9\u7528\u6237\u770B\u3002\u53EA\u5728\u540C\u65F6\u4F20\u4E86 sandbox_permissions \u65F6\u6709\u610F\u4E49\uFF0C\u5355\u72EC\u7ED9\u4F1A\u88AB\u62D2\u3002"
906
+ description: "One sentence on why the whole session has to cross the boundary, shown to the user. Only meaningful together with sandbox_permissions; on its own it is rejected."
895
907
  }
896
908
  },
897
909
  required: []
@@ -913,8 +925,8 @@ var shellOpen = {
913
925
  return Promise.resolve(
914
926
  fail(
915
927
  2006,
916
- t("shell.workdir_out_of_bounds", { workdir, root: baseDir }),
917
- t("shell.workdir_suggestion")
928
+ t("shell.workdir_out_of_bounds", { workdir, root: baseDir }, "en"),
929
+ t("shell.workdir_suggestion", void 0, "en")
918
930
  )
919
931
  );
920
932
  }
@@ -926,16 +938,16 @@ var shellOpen = {
926
938
  return Promise.resolve(
927
939
  fail(
928
940
  2006,
929
- t("shell.limit_reached", { limit: opened.limit, list }),
930
- t("shell.limit_suggestion")
941
+ t("shell.limit_reached", { limit: opened.limit, list }, "en"),
942
+ t("shell.limit_suggestion", void 0, "en")
931
943
  )
932
944
  );
933
945
  }
934
946
  return Promise.resolve(
935
947
  fail(
936
948
  2005,
937
- t("shell.spawn_failed", { message: opened.message + opened.hint }),
938
- t("shell.spawn_failed_suggestion")
949
+ t("shell.spawn_failed", { message: opened.message + opened.hint }, "en"),
950
+ t("shell.spawn_failed_suggestion", void 0, "en")
939
951
  )
940
952
  );
941
953
  }
@@ -950,15 +962,18 @@ function resolveWorkdir(workdir, baseDir) {
950
962
  }
951
963
  var shellSend = {
952
964
  name: "shell_send",
953
- description: '\u5F80\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\u91CC\u53D1\u8F93\u5165\uFF0C\u7B49 wait \u6BEB\u79D2\u4E4B\u540E\u628A\u8FD9\u6BB5\u65F6\u95F4\u7684\u8F93\u51FA\u4EA4\u56DE\u6765\u3002**\u6362\u884C\u8981\u81EA\u5DF1\u5E26**\uFF1Ainput \u662F\u9010\u5B57\u5199\u8FDB\u53BB\u7684\uFF0C"pwd" \u53EA\u662F\u628A\u4E09\u4E2A\u5B57\u7B26\u6253\u4E0A\u53BB\uFF0C"pwd\\n" \u624D\u4F1A\u6267\u884C\u3002Ctrl+C \u5C31\u662F\u53D1 "\\x03"\uFF08\u8FD9\u6BD4\u7ED9\u8FDB\u7A0B\u53D1\u4FE1\u53F7\u66F4\u51C6\uFF0C\u7528\u6237\u5728\u771F\u7EC8\u7AEF\u91CC\u6309\u7684\u6B63\u662F\u8FD9\u6761\u8DEF\uFF09\u3002\u8F93\u51FA\u6CA1\u7B49\u591F\u5C31\u518D\u7528 shell_read \u63A5\u7740\u53D6\uFF08\u6E38\u6807\u63A5\u4E0A\u6B21\u7684 nextCursor\uFF09\u3002\u53D1\u8FDB\u53BB\u7684\u5185\u5BB9**\u548C terminal \u8D70\u540C\u4E00\u6761\u5371\u9669\u547D\u4EE4\u8868\u548C\u6743\u9650\u5224\u5B9A** \u2014\u2014 \u6301\u4E45\u4F1A\u8BDD\u4E0D\u662F\u65C1\u8DEF\u3002',
965
+ description: 'Write input into a persistent session and return what it printed while waiting. You must include the newline yourself: input is written character by character, so "pwd" types three letters and "pwd\\n" runs it. Ctrl+C is sending "\\x03". If the output is not all there yet, read the rest with shell_read, continuing from the returned nextCursor. Whatever you send goes through the same dangerous-command table and permission checks as terminal \u2014 a persistent session is not a way around them.',
954
966
  parameters: {
955
967
  type: "object",
956
968
  properties: {
957
- id: { type: "string", description: "\u4F1A\u8BDD id\uFF0C\u4F8B\u5982 s1" },
958
- input: { type: "string", description: "\u9010\u5B57\u5199\u8FDB\u4F1A\u8BDD\u7684\u8F93\u5165\uFF0C\u901A\u5E38\u8981\u4EE5 \\n \u7ED3\u5C3E" },
969
+ id: { type: "string", description: "Session id, e.g. s1." },
970
+ input: {
971
+ type: "string",
972
+ description: "Text written into the session verbatim; usually ends with \\n."
973
+ },
959
974
  wait: {
960
975
  type: "number",
961
- description: `\u7B49\u591A\u4E45\u518D\u8FD4\u56DE\u8F93\u51FA\uFF08\u6BEB\u79D2\uFF0C\u9ED8\u8BA4 ${DEFAULT_WAIT_MS}\uFF0C\u6700\u5927 ${MAX_WAIT_MS}\uFF09`
976
+ description: `How long to wait before returning output, in milliseconds (default ${DEFAULT_WAIT_MS}, max ${MAX_WAIT_MS}).`
962
977
  }
963
978
  },
964
979
  required: ["id", "input"]
@@ -975,13 +990,18 @@ var shellSend = {
975
990
  execute: async (args, ctx) => {
976
991
  const id = String(args["id"] ?? "");
977
992
  const input = String(args["input"] ?? "");
978
- if (!input) return fail(2004, t("shell.empty_input"), t("shell.empty_input_suggestion"));
993
+ if (!input)
994
+ return fail(
995
+ 2004,
996
+ t("shell.empty_input", void 0, "en"),
997
+ t("shell.empty_input_suggestion", void 0, "en")
998
+ );
979
999
  const danger = checkDangerousCommand(input);
980
1000
  if (danger.dangerous) {
981
1001
  return fail(
982
1002
  2003,
983
- t("shell.dangerous", { desc: danger.desc ?? "" }),
984
- t("shell.dangerous_suggestion", { input: input.trim() })
1003
+ t("shell.dangerous", { desc: danger.desc ?? "" }, "en"),
1004
+ t("shell.dangerous_suggestion", { input: input.trim() }, "en")
985
1005
  );
986
1006
  }
987
1007
  const requested = Number(args["wait"]);
@@ -994,12 +1014,15 @@ var shellSend = {
994
1014
  };
995
1015
  var shellRead = {
996
1016
  name: "shell_read",
997
- description: `\u589E\u91CF\u8BFB\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\u7684\u8F93\u51FA\u3002\u53C2\u6570: id(\u5FC5\u586B), since(\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF0C\u53EA\u53D6\u65B0\u589E\u90E8\u5206)\u3002\u5355\u6B21\u6700\u591A ${MAX_SHELL_CHUNK} \u5B57\u8282\uFF0C\u8F93\u51FA\u5F88\u957F\u65F6\u5206\u6B21\u53D6\uFF1B\u4F1A\u8BDD\u4E0D\u5728\u8DD1\u4E86\u4E5F\u8BFB\u5F97\u5230\uFF08\u7F13\u51B2\u91CC\u90A3\u6BB5\u8F93\u51FA\u8FD8\u5728\uFF09\uFF0C\u6D3B\u4E0D\u6D3B\u7740\u770B\u56DE\u6267\u7B2C\u4E00\u884C\u3002`,
1017
+ description: "Read more output from a persistent session, starting where the last read left off. Also works after the session has exited \u2014 the buffered output is still there.",
998
1018
  parameters: {
999
1019
  type: "object",
1000
1020
  properties: {
1001
- id: { type: "string", description: "\u4F1A\u8BDD id\uFF0C\u4F8B\u5982 s1" },
1002
- since: { type: "number", description: "\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF1B\u4E0D\u7ED9\u5C31\u4ECE\u5934\u53D6" }
1021
+ id: { type: "string", description: "Session id, e.g. s1." },
1022
+ since: {
1023
+ type: "number",
1024
+ description: `nextCursor from the previous reply; omit it to read from the start. At most ${MAX_SHELL_CHUNK} bytes per call.`
1025
+ }
1003
1026
  },
1004
1027
  required: ["id"]
1005
1028
  },
@@ -1015,10 +1038,10 @@ var shellRead = {
1015
1038
  };
1016
1039
  var shellClose = {
1017
1040
  name: "shell_close",
1018
- description: "\u5173\u6389\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\uFF08\u6740\u6574\u68F5\u8FDB\u7A0B\u6811\uFF0C\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B)\u3002\u540D\u989D\u6EE1\u4E86\u3001\u6216\u8005\u8FD9\u4E2A\u73AF\u5883\u4E0D\u518D\u9700\u8981\u4E86\u5C31\u5173\u6389 \u2014\u2014 \u4F1A\u8BDD\u6D3B\u7740\u5C31\u4E00\u76F4\u5360\u4E00\u4E2A\u540D\u989D\u3002",
1041
+ description: "Close a persistent session, killing its whole process tree including anything it started. Close sessions you no longer need \u2014 each live one holds a slot.",
1019
1042
  parameters: {
1020
1043
  type: "object",
1021
- properties: { id: { type: "string", description: "\u4F1A\u8BDD id" } },
1044
+ properties: { id: { type: "string", description: "Session id." } },
1022
1045
  required: ["id"]
1023
1046
  },
1024
1047
  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
@@ -1033,7 +1056,7 @@ var shellClose = {
1033
1056
  };
1034
1057
  var shellList = {
1035
1058
  name: "shell_list",
1036
- description: "\u5217\u51FA\u672C\u6B21\u4F1A\u8BDD\u5F00\u8FC7\u7684\u6301\u4E45 shell \u4F1A\u8BDD\uFF1Aid\u3001\u5DE5\u4F5C\u76EE\u5F55\u3001\u6D3B\u4E86\u591A\u4E45\u3001\u7A7A\u95F2\u591A\u4E45\u3001\u8F93\u51FA\u5B57\u8282\u6570\u3002\u4E0D\u786E\u5B9A\u624B\u91CC\u6709\u54EA\u4E9B\u4F1A\u8BDD\u3001\u6216\u8005\u649E\u4E0A\u540D\u989D\u4E0A\u9650\u65F6\u5148\u770B\u8FD9\u4E2A\u3002",
1059
+ description: `List the persistent sessions opened in this session \u2014 id, working directory, age, idle time and output size.`,
1037
1060
  parameters: { type: "object", properties: {}, required: [] },
1038
1061
  annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
1039
1062
  operation: "file_read",
@@ -1054,66 +1077,66 @@ var SHELL_TOOLS = [
1054
1077
  import { getJob as getJob3, listJobs as listJobs3, readJob as readJob3, stopJob as stopJob3, waitJob as waitJob2 } from "@epoch-agent/infra";
1055
1078
  // src/job-notice.ts
1056
1079
  var KIND_MARK = {
1057
- command: "\u547D\u4EE4",
1058
- shell: "\u4F1A\u8BDD",
1059
- agent: "\u5B50 agent"
1080
+ command: "command",
1081
+ shell: "session",
1082
+ agent: "subagent"
1060
1083
  };
1061
1084
  function stateOf2(status, exitCode, seconds, kind) {
1062
1085
  const agent = kind === "agent";
1063
1086
  switch (status) {
1064
1087
  case "running":
1065
- return `\u8FD0\u884C\u4E2D ${seconds}s`;
1088
+ return `running ${seconds}s`;
1066
1089
  case "exited":
1067
- return agent ? "\u5DF2\u7ED3\u675F" : `\u5DF2\u7ED3\u675F\uFF0C\u9000\u51FA\u7801 ${exitCode}`;
1090
+ return agent ? "finished" : `finished, exit code ${exitCode}`;
1068
1091
  case "killed":
1069
- return "\u5DF2\u505C\u6B62";
1092
+ return "stopped";
1070
1093
  case "closed":
1071
- return "\u5DF2\u5173\u95ED";
1094
+ return "closed";
1072
1095
  case "reaped":
1073
- return "\u7A7A\u95F2\u5DF2\u88AB\u56DE\u6536";
1096
+ return "reclaimed while idle";
1074
1097
  case "failed":
1075
- return agent ? "\u5931\u8D25" : "\u542F\u52A8\u5931\u8D25";
1098
+ return agent ? "failed" : "failed to start";
1076
1099
  }
1077
1100
  }
1078
1101
  function describeJob(info) {
1079
1102
  const dur = Math.round(((info.endedAt ?? Date.now()) - info.startedAt) / 1e3);
1080
- const trunc = info.truncated ? "\uFF0C\u5F00\u5934\u5DF2\u6EDA\u51FA\u7F13\u51B2" : "";
1081
- return `${info.id} [${KIND_MARK[info.kind]}] ${stateOf2(info.status, info.exitCode, dur, info.kind)}\uFF08${info.outputBytes} \u5B57\u8282\u8F93\u51FA${trunc}\uFF09 ${info.label}`;
1103
+ const trunc = info.truncated ? ", the start has scrolled out of the buffer" : "";
1104
+ return `${info.id} [${KIND_MARK[info.kind]}] ${stateOf2(info.status, info.exitCode, dur, info.kind)} (${info.outputBytes} bytes of output${trunc}) ${info.label}`;
1082
1105
  }
1083
- var NO_JOBS = "\u6CA1\u6709\u540E\u53F0\u4F5C\u4E1A\u3002\u7528 terminal \u7684 background: true \u8D77\u4E00\u6761\u540E\u53F0\u547D\u4EE4\uFF0Cshell_open \u5F00\u4E00\u4E2A\u6301\u4E45 shell \u4F1A\u8BDD\uFF0C\u6216\u8005 delegate_task({ background: true }) \u6D3E\u4E00\u6279\u5B50\u4EFB\u52A1\u3002";
1106
+ var NO_JOBS = "No background jobs. Start a background command with terminal background: true, open a persistent shell session with shell_open, or dispatch subagents with delegate_task({ background: true }).";
1084
1107
  function listHead2(count) {
1085
- return `${count} \u4E2A\u540E\u53F0\u4F5C\u4E1A\uFF08\u540E\u53F0\u547D\u4EE4 + \u6301\u4E45 shell \u4F1A\u8BDD + \u540E\u53F0\u5B50 agent\uFF0C\u4E00\u8D77\u5217\uFF09`;
1108
+ return `${count} background job(s) (background commands + persistent shell sessions + background subagents, listed together)`;
1086
1109
  }
1087
1110
  function notFoundNotice(id) {
1088
- return `\u6CA1\u6709\u7F16\u53F7\u4E3A ${id} \u7684\u540E\u53F0\u4F5C\u4E1A`;
1111
+ return `No background job with id ${id}`;
1089
1112
  }
1090
- var NOT_FOUND_SUGGESTION = "\u7528 task_list \u770B\u5F53\u524D\u6709\u54EA\u4E9B\uFF08\u540E\u53F0\u547D\u4EE4\u548C\u6301\u4E45\u4F1A\u8BDD\u90FD\u5728\u91CC\u9762\uFF09";
1091
- var NO_NEW_OUTPUT2 = "\uFF08\u8FD9\u4E00\u6BB5\u6CA1\u6709\u65B0\u8F93\u51FA\uFF09";
1113
+ var NOT_FOUND_SUGGESTION = "Use task_list to see what exists (background commands and persistent sessions are both in there)";
1114
+ var NO_NEW_OUTPUT2 = "(no new output in this range)";
1092
1115
  function waitTimedOutNotice(seconds) {
1093
1116
  return `
1094
- \u7B49\u4E86 ${seconds}s \u8FD8\u6CA1\u7ED3\u675F\uFF0C**\u6CA1\u6709\u505C\u5B83**\u3002\u53EF\u4EE5\u63A5\u7740\u5E72\u522B\u7684\uFF0C\u6216\u518D\u7B49\u4E00\u6B21\u3002`;
1117
+ Waited ${seconds}s and it has not finished yet \u2014 **it was not stopped**. You can go do something else, or wait again.`;
1095
1118
  }
1096
1119
  function waitAbortedNotice(id) {
1097
1120
  return `
1098
- \u7528\u6237\u4E2D\u6B62\u4E86\u8FD9\u6B21\u7B49\u5F85\uFF0C**\u6CA1\u6709\u505C\u5B83**\u3002${id} \u8FD8\u5728\u8DD1\uFF1A\u8981\u770B\u5B83\u73B0\u5728\u7684\u72B6\u6001\u7528 task_list\uFF0C\u8981\u7EE7\u7EED\u7B49\u518D\u8C03\u4E00\u6B21 task_wait\uFF0C\u8981\u771F\u7684\u6536\u6389\u5B83\u7528 task_stop\u3002`;
1121
+ The user aborted this wait \u2014 **it was not stopped**. ${id} is still running: use task_list to see its current status, call task_wait again to keep waiting, or task_stop to really stop it.`;
1099
1122
  }
1100
- var WAIT_DONE = "\n\u7528 task_output \u53D6\u8F93\u51FA\u3002";
1123
+ var WAIT_DONE = "\nUse task_output to read the output.";
1101
1124
  function neverEndsNotice(id) {
1102
1125
  return `
1103
- ${id} \u662F\u4E00\u4E2A\u6301\u4E45 shell \u4F1A\u8BDD\uFF0C\u5B83\u6CA1\u6709\u300C\u7ED3\u675F\u300D\u8FD9\u4E2A\u72B6\u6001 \u2014\u2014 \u4E00\u76F4\u7B49\u4E0B\u53BB\u4E5F\u4E0D\u4F1A\u6709\u7ED3\u679C\u3002
1104
- \u8981\u770B\u5B83\u73B0\u5728\u7684\u8F93\u51FA\u7528 shell_read({ id: '${id}' })\uFF0C\u8981\u53D1\u4E0B\u4E00\u53E5\u7528 shell_send\uFF0C\u8981\u6536\u6389\u5B83\u7528 shell_close \u6216 task_stop\u3002`;
1126
+ ${id} is a persistent shell session and has no "finished" state \u2014 waiting will never produce a result.
1127
+ Use shell_read({ id: '${id}' }) to see its current output, shell_send to send the next line, and shell_close or task_stop to close it.`;
1105
1128
  }
1106
1129
  function stoppedNotice(id, kind) {
1107
1130
  if (kind === "shell") {
1108
- return `${id} \u5DF2\u5173\u95ED\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u90A3\u4E2A\u4F1A\u8BDD\u91CC\u7684\u73AF\u5883\uFF08cd / venv / REPL\uFF09\u6CA1\u4E86\uFF0C\u8981\u7528\u5F97\u91CD\u5F00\u4E00\u4E2A\u3002`;
1131
+ return `${id} closed (along with any processes it started). The environment in that session (cd / venv / REPL) is gone \u2014 open a new one if you need it.`;
1109
1132
  }
1110
1133
  if (kind === "agent") {
1111
- return `${id} \u5DF2\u505C\u6B62\uFF08\u5B50\u4EFB\u52A1\u4E0D\u4F1A\u518D\u5F80\u4E0B\u8DD1\uFF09\u3002\u5B83\u5DF2\u7ECF\u8D77\u8FC7\u7684\u540E\u53F0\u547D\u4EE4\u5F52\u5230\u4E86\u4F60\u8FD9\u4E2A\u4F1A\u8BDD\u540D\u4E0B\uFF0C\u8981\u6536\u5F97\u5355\u72EC task_stop\u3002`;
1134
+ return `${id} stopped (its subtasks will not run any further). Background commands it already started now belong to your session \u2014 stop those separately with task_stop.`;
1112
1135
  }
1113
- return `${id} \u5DF2\u505C\u6B62\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002`;
1136
+ return `${id} stopped (along with any processes it started).`;
1114
1137
  }
1115
1138
  function alreadyStoppedNotice(id) {
1116
- return `${id} \u5DF2\u7ECF\u4E0D\u5728\u8FD0\u884C\u4E2D\u4E86\u3002`;
1139
+ return `${id} is no longer running.`;
1117
1140
  }
1118
1141
  // src/jobs.ts
1119
1142
  import { jobDetail as jobDetail3 } from "@epoch-agent/infra";
@@ -1136,7 +1159,7 @@ function notFound2(id) {
1136
1159
  }
1137
1160
  var taskList = {
1138
1161
  name: "task_list",
1139
- description: "\u5217\u51FA\u672C\u6B21\u4F1A\u8BDD\u8D77\u8FC7\u7684**\u540E\u53F0\u4F5C\u4E1A** \u2014\u2014 terminal \u7684 background: true \u8D77\u7684\u540E\u53F0\u547D\u4EE4\u3001shell_open \u5F00\u7684\u6301\u4E45 shell \u4F1A\u8BDD\u3001delegate_task({ background: true }) \u6D3E\u51FA\u53BB\u7684\u540E\u53F0\u5B50 agent\uFF0C\u4E09\u79CD\u4E00\u8D77\u5217\uFF0C\u6BCF\u884C\u6807\u51FA\u662F\u54EA\u4E00\u79CD\uFF08[\u547D\u4EE4] / [\u4F1A\u8BDD] / [\u5B50 agent]\uFF09\u3002\u542B\u72B6\u6001\u3001\u9000\u51FA\u7801\u3001\u8F93\u51FA\u5B57\u8282\u6570\u3002\u4E0D\u786E\u5B9A\u624B\u91CC\u6709\u4EC0\u4E48\u5728\u8DD1\u5C31\u5148\u770B\u8FD9\u4E2A\u3002",
1162
+ description: "List the background jobs started in this session: commands started with terminal background:true, persistent sessions opened with shell_open, and subagents dispatched with delegate_task({ background: true }). Each line says which kind it is ([command] / [session] / [subagent]), with status, exit code and output size.",
1140
1163
  parameters: { type: "object", properties: {}, required: [] },
1141
1164
  annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
1142
1165
  operation: "file_read",
@@ -1148,15 +1171,18 @@ var taskList = {
1148
1171
  };
1149
1172
  var taskOutputTool = {
1150
1173
  name: "task_output",
1151
- description: `\u53D6\u4E00\u4E2A\u540E\u53F0\u4F5C\u4E1A\u7684\u8F93\u51FA\uFF08\u540E\u53F0\u547D\u4EE4 t1\u3001\u6301\u4E45\u4F1A\u8BDD s1\u3001\u540E\u53F0\u5B50 agent a1 \u90FD\u884C\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B), since(\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF0C\u7528\u6765\u53EA\u53D6\u65B0\u589E\u90E8\u5206)\u3002\u5355\u6B21\u6700\u591A ${MAX_OUTPUT_CHUNK} \u5B57\u8282\uFF1B\u8F93\u51FA\u5F88\u957F\u65F6\u4F1A\u5206\u6B21\u53D6\uFF0C\u8FD4\u56DE\u91CC\u4F1A\u8BF4\u660E\u8FD8\u6709\u6CA1\u6709\u66F4\u591A\u3002`,
1174
+ description: "Read the output of a background job: a background command (t1), a persistent session (s1) or a background subagent (a1). Pass since to get only what is new; the reply says whether more remains.",
1152
1175
  parameters: {
1153
1176
  type: "object",
1154
1177
  properties: {
1155
1178
  id: {
1156
1179
  type: "string",
1157
- description: "\u4F5C\u4E1A id\uFF0C\u4F8B\u5982 t1\uFF08\u540E\u53F0\u547D\u4EE4\uFF09\u3001s1\uFF08\u6301\u4E45\u4F1A\u8BDD\uFF09\u6216 a1\uFF08\u540E\u53F0\u5B50 agent\uFF09"
1180
+ description: "Job id, e.g. t1 (background command), s1 (persistent session) or a1 (background subagent)."
1158
1181
  },
1159
- since: { type: "number", description: "\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF1B\u4E0D\u7ED9\u5C31\u4ECE\u5934\u53D6" }
1182
+ since: {
1183
+ type: "number",
1184
+ description: `nextCursor from the previous reply; omit it to read from the start. At most ${MAX_OUTPUT_CHUNK} bytes per call.`
1185
+ }
1160
1186
  },
1161
1187
  required: ["id"]
1162
1188
  },
@@ -1197,12 +1223,15 @@ ${sbErr.suggestion}`);
1197
1223
  };
1198
1224
  var taskWait = {
1199
1225
  name: "task_wait",
1200
- description: "\u963B\u585E\u7B49\u4E00\u4E2A\u540E\u53F0\u4F5C\u4E1A\u7ED3\u675F\u3002\u53C2\u6570: id(\u5FC5\u586B), timeoutMs(\u9ED8\u8BA4 30000\uFF0C\u6700\u5927 300000)\u3002**\u8D85\u65F6\u4E0D\u4F1A\u6740\u5B83** \u2014\u2014 \u53EA\u662F\u544A\u8BC9\u4F60\u8FD8\u5728\u8DD1\uFF0C\u8981\u505C\u7528 task_stop\u3002\u540E\u53F0\u5B50 agent\uFF08a1\uFF09\u4E5F\u80FD\u7B49\uFF0C\u7B49\u5230\u4E86\u7528 task_output \u53D6\u7ED3\u8BBA\u3002\u6301\u4E45 shell \u4F1A\u8BDD\uFF08s1\uFF09\u538B\u6839\u6CA1\u6709\u300C\u7ED3\u675F\u300D\u8FD9\u4E2A\u72B6\u6001\uFF0C\u7B49\u5B83\u4F1A**\u7ACB\u523B**\u8FD4\u56DE\u4E00\u53E5\u8BF4\u660E\u800C\u4E0D\u662F\u5E72\u7B49\u3002",
1226
+ description: "Block until a background job finishes. A timeout does not kill it \u2014 it just reports that it is still running; use task_stop to stop it. A persistent session (s1) has no notion of finishing, so waiting on one returns a note immediately instead of blocking.",
1201
1227
  parameters: {
1202
1228
  type: "object",
1203
1229
  properties: {
1204
- id: { type: "string", description: "\u4F5C\u4E1A id" },
1205
- timeoutMs: { type: "number", description: "\u6700\u591A\u7B49\u591A\u4E45\uFF08\u6BEB\u79D2\uFF09" }
1230
+ id: { type: "string", description: "Job id." },
1231
+ timeoutMs: {
1232
+ type: "number",
1233
+ description: `How long to wait at most, in milliseconds (default ${DEFAULT_WAIT_MS2}, max ${MAX_WAIT_MS2}).`
1234
+ }
1206
1235
  },
1207
1236
  required: ["id"]
1208
1237
  },
@@ -1224,10 +1253,10 @@ var taskWait = {
1224
1253
  };
1225
1254
  var taskStop = {
1226
1255
  name: "task_stop",
1227
- description: "\u505C\u6389\u4E00\u4E2A\u540E\u53F0\u4F5C\u4E1A\uFF08\u6740\u6574\u68F5\u8FDB\u7A0B\u6811\uFF0C\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B)\u3002\u540E\u53F0\u547D\u4EE4\uFF08t1\uFF09\u3001\u6301\u4E45\u4F1A\u8BDD\uFF08s1\uFF09\u3001\u540E\u53F0\u5B50 agent\uFF08a1\uFF09\u90FD\u80FD\u505C \u2014\u2014\u505C\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\u7B49\u4EF7\u4E8E shell_close\uFF0C\u90A3\u4E2A\u4F1A\u8BDD\u91CC\u7684\u73AF\u5883\uFF08cd / venv / REPL\uFF09\u4F1A\u4E00\u8D77\u6CA1\uFF1B\u505C\u4E00\u4E2A\u540E\u53F0\u5B50 agent \u4F1A\u628A\u5B83\u7684\u5B50\u4EFB\u52A1\u4E00\u8D77\u6536\u6389\uFF08\u5DF2\u7ECF\u8D77\u8FC7\u7684\u540E\u53F0\u547D\u4EE4\u4E0D\u8DDF\u7740\u6CA1\uFF09\u3002",
1256
+ description: "Stop a background job, killing its whole process tree including anything it started. Stopping a persistent session is the same as shell_close: its environment (cd / venv / REPL) goes with it. Stopping a background subagent also stops its subtasks, but not background commands it already started.",
1228
1257
  parameters: {
1229
1258
  type: "object",
1230
- properties: { id: { type: "string", description: "\u4F5C\u4E1A id" } },
1259
+ properties: { id: { type: "string", description: "Job id." } },
1231
1260
  required: ["id"]
1232
1261
  },
1233
1262
  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
@@ -1247,7 +1276,7 @@ var TASK_TOOLS = [taskList, taskOutputTool, taskWait, taskStop];
1247
1276
  // src/index.ts
1248
1277
  var DEFAULT_TIMEOUT = 6e4;
1249
1278
  var PTY_TIMEOUT = 3e4;
1250
- var CANCELLED = "\u547D\u4EE4\u5DF2\u88AB\u53D6\u6D88";
1279
+ var CANCELLED = "Command cancelled";
1251
1280
  function detectCd(command) {
1252
1281
  const trimmed = command.trim();
1253
1282
  const cdMatch = trimmed.match(/^cd\s+([^&|;]+)$/);
@@ -1270,41 +1299,41 @@ function toSandboxFailure(sb, output, duration) {
1270
1299
  duration
1271
1300
  };
1272
1301
  }
1273
- var CD_NOTICE = (target) => `[\u63D0\u793A] cd \u53EA\u5728\u672C\u6B21\u5B50 shell \u5185\u751F\u6548\uFF0C\u4E0B\u6B21\u8C03\u7528\u4ECD\u5728\u539F\u5DE5\u4F5C\u76EE\u5F55\u3002\u82E5\u540E\u7EED\u547D\u4EE4\u9700\u8981\u5728 ${target} \u4E0B\u6267\u884C\uFF0C\u8BF7\u4F20 workdir \u53C2\u6570\uFF0C\u6216\u5199\u6210 "cd ${target} && <\u547D\u4EE4>"\u3002`;
1302
+ var CD_NOTICE = (target) => `[note] cd only takes effect inside this subshell; the next call still runs in the original working directory. If the following commands have to run in ${target}, pass the workdir parameter, or write it as "cd ${target} && <command>".`;
1274
1303
  var terminalTool = {
1275
1304
  name: "terminal",
1276
- description: "\u5728\u7EC8\u7AEF\u4E2D\u6267\u884C shell \u547D\u4EE4\u3002\u652F\u6301\u540E\u53F0(background)\u3001PTY \u4EA4\u4E92(pty)\u3001cwd \u5207\u6362\u3002\u9002\u7528\u4E8E\u811A\u672C\u3001\u6784\u5EFA\u3001\u5B89\u88C5\u3001\u4EA4\u4E92\u5F0F\u547D\u4EE4\u7B49\u3002",
1305
+ description: "Run a shell command and return its output. Use it for one-off commands, builds, installs and interactive prompts; for state that has to survive between calls, use shell_open instead.",
1277
1306
  parameters: {
1278
1307
  type: "object",
1279
1308
  properties: {
1280
1309
  command: {
1281
1310
  type: "string",
1282
- description: "\u8981\u6267\u884C\u7684 shell \u547D\u4EE4"
1311
+ description: "Shell command to run."
1283
1312
  },
1284
1313
  background: {
1285
1314
  type: "boolean",
1286
- description: "\u540E\u53F0\u6267\u884C\uFF1A\u7ACB\u5373\u8FD4\u56DE\u4EFB\u52A1 id \u4E0D\u7B49\u7ED3\u679C\uFF0C\u914D\u5408 task_output / task_wait / task_stop \u7528\u3002\u9002\u5408\u6784\u5EFA\u3001\u8DD1 watch\u3001\u8D77\u670D\u52A1\uFF08\u8D77\u670D\u52A1\u518D curl \u5B83\u8FD9\u6761\u8DEF\u53EA\u80FD\u8FD9\u4E48\u8D70\uFF09\u3002**\u6743\u9650\u5224\u5B9A\u548C\u524D\u53F0\u5B8C\u5168\u4E00\u6837**\uFF0C\u540E\u53F0\u4E0D\u662F\u7ED5\u8FC7\u786E\u8BA4\u7684\u65C1\u8DEF\u3002"
1315
+ description: "Run it in the background: return a job id immediately instead of waiting, and drive it with task_output / task_wait / task_stop. This is the only way to start a server and then curl it. Permission checks are exactly the same as in the foreground \u2014 background is not a way around a confirmation."
1287
1316
  },
1288
1317
  pty: {
1289
1318
  type: "boolean",
1290
- description: "PTY \u6A21\u5F0F\uFF1A\u7528\u4E8E\u4EA4\u4E92\u5F0F\u547D\u4EE4\uFF08npm init\u3001git add -p \u7B49\uFF09\u3002[Hermes/Codex]"
1319
+ description: "Run it in a PTY. Use this for interactive commands (npm init, git add -p and the like). [Hermes/Codex]"
1291
1320
  },
1292
1321
  stdin: {
1293
1322
  type: "string",
1294
- description: "PTY \u6A21\u5F0F\u4E0B\u53D1\u9001\u7ED9\u547D\u4EE4\u7684\u6807\u51C6\u8F93\u5165"
1323
+ description: "Standard input to send to the command in PTY mode."
1295
1324
  },
1296
1325
  workdir: {
1297
1326
  type: "string",
1298
- description: "\u5DE5\u4F5C\u76EE\u5F55\uFF08\u5FC5\u987B\u5728\u5DE5\u4F5C\u533A\u5185\uFF0C\u76F8\u5BF9\u8DEF\u5F84\u6309\u5DE5\u4F5C\u533A\u6839\u89E3\u6790\uFF09"
1327
+ description: "Working directory. Must be inside the workspace; a relative path is resolved against the workspace root."
1299
1328
  },
1300
1329
  [SANDBOX_PERMISSIONS_PARAM2]: {
1301
1330
  type: "string",
1302
1331
  enum: [...ESCALATION_TARGETS2],
1303
- description: "\u4EC5\u5F53\u547D\u4EE4\u88AB\u6C99\u7BB1\u6321\u4E0B\uFF08\u9519\u8BEF 2008/2009\uFF09\u4E14\u786E\u8BA4\u8FD9\u6B21\u5FC5\u987B\u8D8A\u754C\u65F6\u624D\u7528\uFF1A\u8BF7\u6C42\u653E\u5F00**\u8FD9\u4E00\u6B21**\u6267\u884C\u7684\u6C99\u7BB1\u8FB9\u754C\u3002\u53D6\u503C\u53EA\u80FD\u662F\u5F53\u524D\u6863\u4F4D\u4E25\u683C\u66F4\u5BBD\u7684\u90A3\u4E00\u9879\uFF0C\u4E14\u5FC5\u987B\u548C justification \u6210\u5BF9\u51FA\u73B0\uFF08\u53EA\u7ED9\u4E00\u4E2A\u6574\u6B21\u8C03\u7528\u76F4\u63A5\u5931\u8D25\uFF09\u3002\u7528\u6237\u4F1A\u5355\u72EC\u770B\u5230\u4E00\u6B21\u5347\u6743\u5BA1\u6279\uFF1B\u53EA\u5BF9\u8FD9\u4E00\u6B21\u8C03\u7528\u751F\u6548\u3002\u522B\u628A\u5B83\u5F53\u4E07\u7528\u5F00\u5173 \u2014\u2014 \u80FD\u628A\u6539\u52A8\u632A\u8FDB\u5DE5\u4F5C\u533A\u3001\u6216\u6362\u6210\u4E0D\u9700\u8981\u8D8A\u754C\u7684\u5199\u6CD5\uFF0C\u5C31\u5148\u90A3\u4E48\u529E\u3002"
1332
+ description: "Only when this command was stopped by the sandbox (error 2008/2009) and it really has to cross the boundary: request a wider sandbox for **this one call**. The value must be strictly wider than the current tier, and it must come with justification (giving only one of the two fails the whole call). The user sees a separate escalation request; it applies to this call only. Do not treat it as a general-purpose switch \u2014 if the work can move inside the workspace or be rewritten, do that first."
1304
1333
  },
1305
1334
  [JUSTIFICATION_PARAM2]: {
1306
1335
  type: "string",
1307
- description: "\u4E00\u53E5\u8BDD\u8BF4\u660E\u4E3A\u4EC0\u4E48\u5FC5\u987B\u8D8A\u754C\uFF0C\u7ED9\u7528\u6237\u770B\uFF08\u4ED6\u636E\u6B64\u51B3\u5B9A\u6279\u4E0D\u6279\uFF09\u3002\u53EA\u5728\u540C\u65F6\u4F20\u4E86 sandbox_permissions \u65F6\u6709\u610F\u4E49\uFF0C\u5355\u72EC\u7ED9\u4F1A\u88AB\u62D2\u3002"
1336
+ description: "One sentence on why the boundary has to be crossed, shown to the user so they can decide. Only meaningful together with sandbox_permissions; on its own it is rejected."
1308
1337
  }
1309
1338
  },
1310
1339
  required: ["command"]
@@ -1329,7 +1358,11 @@ var terminalTool = {
1329
1358
  return {
1330
1359
  success: false,
1331
1360
  output: "",
1332
- error: { code: 2004, message: "\u547D\u4EE4\u4E0D\u80FD\u4E3A\u7A7A", suggestion: "\u8BF7\u63D0\u4F9B\u8981\u6267\u884C\u7684\u547D\u4EE4" },
1361
+ error: {
1362
+ code: 2004,
1363
+ message: "Command must not be empty",
1364
+ suggestion: "Provide the command to run"
1365
+ },
1333
1366
  duration: 0
1334
1367
  };
1335
1368
  }
@@ -1340,8 +1373,8 @@ var terminalTool = {
1340
1373
  output: "",
1341
1374
  error: {
1342
1375
  code: 2003,
1343
- message: `\u5371\u9669\u64CD\u4F5C\u5DF2\u88AB\u62E6\u622A: ${danger.desc}`,
1344
- suggestion: `\u547D\u4EE4 "${command}" \u6D89\u53CA ${danger.desc}`
1376
+ message: `Dangerous operation blocked: ${danger.desc}`,
1377
+ suggestion: `The command "${command}" involves ${danger.desc}`
1345
1378
  },
1346
1379
  duration: 0
1347
1380
  };
@@ -1356,8 +1389,8 @@ var terminalTool = {
1356
1389
  output: "",
1357
1390
  error: {
1358
1391
  code: 2006,
1359
- message: `workdir \u8D8A\u754C: ${workdir} \u4E0D\u5728\u5DE5\u4F5C\u533A ${baseDir} \u5185`,
1360
- suggestion: "\u53EA\u80FD\u5728\u5DE5\u4F5C\u533A\u5185\u6267\u884C\u547D\u4EE4\uFF1B\u5982\u9700\u8DE8\u76EE\u5F55\u64CD\u4F5C\u8BF7\u8BF4\u660E\u7406\u7531\u7531\u7528\u6237\u786E\u8BA4"
1392
+ message: `workdir out of bounds: ${workdir} is not inside the workspace ${baseDir}`,
1393
+ suggestion: "Commands can only run inside the workspace; to work across directories, explain why and let the user confirm"
1361
1394
  },
1362
1395
  duration: 0
1363
1396
  };
@@ -1376,7 +1409,11 @@ var terminalTool = {
1376
1409
  return {
1377
1410
  success: false,
1378
1411
  output: "",
1379
- error: { code: 2006, message: started.error, suggestion: "\u7528 task_stop \u505C\u6389\u4E00\u4E2A\u518D\u8BD5" },
1412
+ error: {
1413
+ code: 2006,
1414
+ message: started.error,
1415
+ suggestion: "Stop one with task_stop and try again"
1416
+ },
1380
1417
  duration: 0
1381
1418
  };
1382
1419
  }
@@ -1385,9 +1422,9 @@ var terminalTool = {
1385
1422
  success: true,
1386
1423
  output: [
1387
1424
  ...bgNotice ? [bgNotice] : [],
1388
- `\u540E\u53F0\u4EFB\u52A1 ${started.task.id} \u5DF2\u542F\u52A8\uFF1A${command}`,
1389
- "task_output \u53D6\u8F93\u51FA \xB7 task_wait \u7B49\u5B83\u7ED3\u675F \xB7 task_stop \u505C\u6389 \xB7 task_list \u770B\u5168\u90E8\u3002",
1390
- "\u6CE8\u610F\uFF1A\u540E\u53F0\u4EFB\u52A1\u6D3B\u4E0D\u8FC7 epoch \u8FDB\u7A0B\uFF0C\u9000\u51FA\u65F6\u4F1A\u88AB\u4E00\u8D77\u6536\u6389\u3002"
1425
+ `Background task ${started.task.id} started: ${command}`,
1426
+ "task_output reads its output \xB7 task_wait waits for it to finish \xB7 task_stop stops it \xB7 task_list lists them all.",
1427
+ "Note: background tasks do not outlive the epoch process \u2014 they are collected when epoch exits."
1391
1428
  ].join("\n"),
1392
1429
  duration: 0
1393
1430
  };
@@ -1438,8 +1475,8 @@ ${CD_NOTICE(cdTarget)}`;
1438
1475
  output: "",
1439
1476
  error: {
1440
1477
  code: 2005,
1441
- message: `PTY \u6267\u884C\u5931\u8D25: ${message}`,
1442
- suggestion: "\u68C0\u67E5 node-pty \u662F\u5426\u6B63\u786E\u5B89\u88C5"
1478
+ message: `PTY execution failed: ${message}`,
1479
+ suggestion: "Check that node-pty is installed correctly"
1443
1480
  },
1444
1481
  duration
1445
1482
  };
@@ -1472,8 +1509,8 @@ ${output}`;
1472
1509
  output,
1473
1510
  error: {
1474
1511
  code: 2002,
1475
- message: `\u547D\u4EE4\u6267\u884C\u8D85\u65F6\uFF08${DEFAULT_TIMEOUT / 1e3} \u79D2\uFF09\uFF0C\u8FDB\u7A0B\u6811\u5DF2\u7EC8\u6B62`,
1476
- suggestion: "\u5C1D\u8BD5\u7B80\u5316\u547D\u4EE4\uFF0C\u6216\u7528 background: true \u653E\u540E\u53F0\u8DD1"
1512
+ message: `Command timed out (${DEFAULT_TIMEOUT / 1e3} seconds); the process tree was terminated`,
1513
+ suggestion: "Try simplifying the command, or run it in the background with background: true"
1477
1514
  },
1478
1515
  duration
1479
1516
  };
@@ -1497,7 +1534,11 @@ ${CD_NOTICE(cdTarget)}`;
1497
1534
  return {
1498
1535
  success: false,
1499
1536
  output: "",
1500
- error: { code: 2005, message: `\u547D\u4EE4\u6267\u884C\u5931\u8D25: ${message}`, suggestion: "\u68C0\u67E5\u547D\u4EE4\u662F\u5426\u6B63\u786E" },
1537
+ error: {
1538
+ code: 2005,
1539
+ message: `Command failed: ${message}`,
1540
+ suggestion: "Check that the command is correct"
1541
+ },
1501
1542
  duration
1502
1543
  };
1503
1544
  }
@@ -1506,7 +1547,7 @@ ${CD_NOTICE(cdTarget)}`;
1506
1547
  var terminalPlugin = {
1507
1548
  name: "@epoch-agent/plugin-terminal",
1508
1549
  version: "0.0.0",
1509
- description: "\u7EC8\u7AEF\u547D\u4EE4\u6267\u884C + PTY \u4EA4\u4E92 + \u540E\u53F0\u4EFB\u52A1 + \u6301\u4E45 shell \u4F1A\u8BDD [Hermes/Codex]",
1550
+ description: "Terminal commands + PTY interaction + background jobs + persistent shell sessions [Hermes/Codex]",
1510
1551
  tools: [terminalTool, ...TASK_TOOLS, ...SHELL_TOOLS]
1511
1552
  };
1512
1553
  export {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@epoch-agent/plugin-terminal",
3
- "version": "3.2.0",
3
+ "version": "4.0.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": "3.2.0",
26
- "@epoch-agent/protocol": "3.2.0"
25
+ "@epoch-agent/infra": "4.0.0",
26
+ "@epoch-agent/protocol": "4.0.0"
27
27
  },
28
28
  "devDependencies": {
29
29
  "@types/node": "^26.1.2",