@epoch-agent/plugin-terminal 3.2.0 → 4.1.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 +6 -2
- package/dist/index.d.ts +195 -332
- package/dist/index.js +173 -132
- package/package.json +3 -3
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("
|
|
97
|
+
const list = running.map((j) => `${j.id} (${j.label})`).join(", ");
|
|
98
98
|
return {
|
|
99
|
-
error:
|
|
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" ?
|
|
198
|
-
const trunc = info.truncated ? "
|
|
199
|
-
return `${info.id} ${state}
|
|
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
|
-
[
|
|
214
|
-
var NO_OUTPUT = "(
|
|
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
|
|
366
|
-
|
|
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
|
|
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({
|
|
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": "
|
|
481
|
-
"workspace-write": "
|
|
482
|
-
"danger-full-access": "
|
|
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 "[
|
|
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 "[
|
|
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 `[
|
|
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 "[
|
|
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 `[
|
|
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 `[
|
|
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:
|
|
510
|
-
suggestion:
|
|
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:
|
|
516
|
-
suggestion: sb.mode === "read-only" ? "
|
|
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
|
-
|
|
550
|
-
|
|
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
|
|
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 = `[
|
|
565
|
+
const body = `[Output is ${formatBytes(full)}; what follows is only a preview]
|
|
562
566
|
${head ? `${head}
|
|
563
|
-
` : ""}\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
|
|
576
|
+
return `(the first ${missed} bytes have scrolled out of the ring buffer)${where}`;
|
|
573
577
|
}
|
|
574
578
|
function describeMore(nextCursor) {
|
|
575
|
-
return
|
|
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
|
|
587
|
+
return `alive ${alive}s (idle ${idle}s)`;
|
|
584
588
|
}
|
|
585
589
|
case "exited":
|
|
586
|
-
return `shell
|
|
590
|
+
return `the shell exited on its own, exit code ${info.exitCode}`;
|
|
587
591
|
case "closed":
|
|
588
|
-
return "
|
|
592
|
+
return "closed";
|
|
589
593
|
case "reaped":
|
|
590
|
-
return
|
|
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 ? "
|
|
595
|
-
return `${info.id} ${stateOf(info)} cwd=${info.cwd}
|
|
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
|
-
|
|
600
|
-
"shell_send
|
|
601
|
-
|
|
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}
|
|
609
|
+
return `${id} closed (along with any processes it started).`;
|
|
606
610
|
}
|
|
607
611
|
function alreadyGoneNotice(id) {
|
|
608
|
-
return `${id}
|
|
612
|
+
return `${id} is no longer running.`;
|
|
609
613
|
}
|
|
610
|
-
var NO_SHELLS = "
|
|
614
|
+
var NO_SHELLS = "No persistent shell sessions. Open one with shell_open.";
|
|
611
615
|
function listHead(count) {
|
|
612
|
-
return `${count}
|
|
616
|
+
return `${count} persistent shell session(s) (at most ${MAX_SHELLS} at a time)`;
|
|
613
617
|
}
|
|
614
|
-
var NO_NEW_OUTPUT = "\
|
|
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
|
-
[
|
|
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(
|
|
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(
|
|
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:
|
|
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: "
|
|
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: "
|
|
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: "
|
|
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: '
|
|
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: "
|
|
958
|
-
input: {
|
|
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:
|
|
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)
|
|
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:
|
|
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: "
|
|
1002
|
-
since: {
|
|
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: "
|
|
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: "
|
|
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:
|
|
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: "
|
|
1058
|
-
shell: "
|
|
1059
|
-
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
|
|
1088
|
+
return `running ${seconds}s`;
|
|
1066
1089
|
case "exited":
|
|
1067
|
-
return agent ? "
|
|
1090
|
+
return agent ? "finished" : `finished, exit code ${exitCode}`;
|
|
1068
1091
|
case "killed":
|
|
1069
|
-
return "
|
|
1092
|
+
return "stopped";
|
|
1070
1093
|
case "closed":
|
|
1071
|
-
return "
|
|
1094
|
+
return "closed";
|
|
1072
1095
|
case "reaped":
|
|
1073
|
-
return "
|
|
1096
|
+
return "reclaimed while idle";
|
|
1074
1097
|
case "failed":
|
|
1075
|
-
return agent ? "
|
|
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 ? "
|
|
1081
|
-
return `${info.id} [${KIND_MARK[info.kind]}] ${stateOf2(info.status, info.exitCode, dur, info.kind)}
|
|
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 = "
|
|
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}
|
|
1108
|
+
return `${count} background job(s) (background commands + persistent shell sessions + background subagents, listed together)`;
|
|
1086
1109
|
}
|
|
1087
1110
|
function notFoundNotice(id) {
|
|
1088
|
-
return
|
|
1111
|
+
return `No background job with id ${id}`;
|
|
1089
1112
|
}
|
|
1090
|
-
var NOT_FOUND_SUGGESTION = "
|
|
1091
|
-
var NO_NEW_OUTPUT2 = "
|
|
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
|
-
|
|
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
|
-
\
|
|
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 = "\
|
|
1123
|
+
var WAIT_DONE = "\nUse task_output to read the output.";
|
|
1101
1124
|
function neverEndsNotice(id) {
|
|
1102
1125
|
return `
|
|
1103
|
-
${id}
|
|
1104
|
-
|
|
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}
|
|
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} \
|
|
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}
|
|
1136
|
+
return `${id} stopped (along with any processes it started).`;
|
|
1114
1137
|
}
|
|
1115
1138
|
function alreadyStoppedNotice(id) {
|
|
1116
|
-
return `${id}
|
|
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: "
|
|
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:
|
|
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: "
|
|
1180
|
+
description: "Job id, e.g. t1 (background command), s1 (persistent session) or a1 (background subagent)."
|
|
1158
1181
|
},
|
|
1159
|
-
since: {
|
|
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: "\
|
|
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: "
|
|
1205
|
-
timeoutMs: {
|
|
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: "
|
|
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: "
|
|
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 = "
|
|
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) => `[
|
|
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: "
|
|
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: "
|
|
1311
|
+
description: "Shell command to run."
|
|
1283
1312
|
},
|
|
1284
1313
|
background: {
|
|
1285
1314
|
type: "boolean",
|
|
1286
|
-
description: "
|
|
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
|
|
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
|
|
1323
|
+
description: "Standard input to send to the command in PTY mode."
|
|
1295
1324
|
},
|
|
1296
1325
|
workdir: {
|
|
1297
1326
|
type: "string",
|
|
1298
|
-
description: "
|
|
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: "
|
|
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: "
|
|
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: {
|
|
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:
|
|
1344
|
-
suggestion:
|
|
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
|
|
1360
|
-
suggestion: "
|
|
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: {
|
|
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
|
-
|
|
1389
|
-
"task_output
|
|
1390
|
-
"\
|
|
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
|
|
1442
|
-
suggestion: "
|
|
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:
|
|
1476
|
-
suggestion: "
|
|
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: {
|
|
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: "
|
|
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 {
|