@prized/sdk 0.0.0-stage → 0.1.1

package/dist/esm/shell.d.ts

@@ -0,0 +1,152 @@
+/** One argument, quoted for a POSIX shell: as Python's shlex.quote does, so both SDKs send the same text. */
+export declare function shellQuote(value: string): string;
+/** A command as one string: a string is passed through, an argv array is quoted. */
+export declare function commandText(command: string | readonly string[]): string;
+/** The template's working directory: where relative paths and commands start. */
+export declare const WORKSPACE_DIR = "/home/prized/work";
+/** A path as the sandbox reads it: relative paths start in the workspace. */
+export declare function sandboxPath(path: string): string;
+export declare const RUNS_DIR = "/home/prized/.prized/runs";
+export declare const RUN_ID_RE: RegExp;
+/**
+ * Minutes (by the sandbox's clock) a cleaned or abandoned run's directory
+ * stays: what keeps a resend of its start from running the command again.
+ * The SDK stops resending a start within minutes, so an hour is ample; each
+ * cleanup then removes the ones older than that, so they never pile up.
+ */
+export declare const CLEANED_KEEP_MIN = 60;
+/** The start script's exit when it launched the command but no pid came within ten seconds: it may yet run. */
+export declare const NO_PID_EXIT = 99;
+/**
+ * The longest time limit a start script renders, in seconds (about 31
+ * years): a longer one is none in all but name, and past 2^63 the shell's
+ * arithmetic would wrap it negative and stop the command at once.
+ */
+export declare const MAX_LIMIT_SEC = 1000000000;
+/**
+ * The script that runs inside the run's session. Positional: $1 the run
+ * directory, $2 the shell, $3 the command, $4 the time limit in whole
+ * seconds ('' for none). No single quotes: it travels inside them.
+ *
+ * A signal sent to the run (HUP, INT, QUIT, TERM) does not end the wrapper,
+ * so it always writes `exit`: one that arrives before the launch means the
+ * command does not start (bar a window of microseconds just before the
+ * fork, where it reaches only the wrapper), and the run ends with that
+ * signal's 128+n code. One that arrives while the command runs reaches the
+ * command itself, in the same process group. USR1 and USR2 are the
+ * command's own to use.
+ *
+ * The caller's PATH (PRIZED_RUN_PATH, from the start script) is the
+ * command's alone: the wrapper and its watchdog keep the launcher's.
+ *
+ * The rest of the caller's env reaches the command as it was. A shell
+ * variable that came from the environment stays exported, so an assignment
+ * to it changes what every child is given: the scripts' own variables are
+ * __pz_ names (a caller's `d` once reached the command as the run's
+ * directory), and the scripts that lead to the command unset theirs first,
+ * so none is exported. Treat the prefix as theirs: a caller's variable
+ * named like one of the start script's or the wrapper's does not reach the
+ * command.
+ *
+ * The limit is a watchdog in the same process group, not timeout(1):
+ * timeout moves the command into a process group of its own, out of reach
+ * of a kill sent to the run. It ignores HUP, INT, QUIT, TERM, USR1 and USR2
+ * (so a kill of the run does not stop it first), checks once a second,
+ * writes `timedout`, sends TERM to the group, and five seconds later KILL to
+ * whatever is left of it. The limit and the command's end race, so `limit`
+ * is claimed once, by whichever comes first (mkdir is atomic): an end that
+ * came first stops the watchdog (only while its pid is still the
+ * watchdog's), and a limit that fired first is left to finish.
+ *
+ * Kept equal to the Python SDK's _WRAPPER (test/run-scripts.test.ts).
+ */
+export declare const WRAPPER: string;
+/** The PATH the start script launches with, whatever the caller's env says. */
+export declare const LAUNCH_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+/**
+ * Start `command` detached. Prints the run's process group id. Safe to send
+ * twice with the same run id: the second send finds the directory and prints
+ * the first one's pid instead of starting it again.
+ *
+ * The caller's PATH reaches the command through the environment
+ * (PRIZED_RUN_PATH, not an argument, which every user of the guest could
+ * read); the launcher itself runs on LAUNCH_PATH, so a PATH of the
+ * caller's never hides setsid or the shell from it.
+ *
+ * `unbuffered` (background and streamed commands, whose output is read as
+ * it is printed) sets PYTHONUNBUFFERED=1 unless the command's environment
+ * already has it: Python's output to a file is otherwise held in a buffer
+ * until it exits.
+ *
+ * `setsid -f` forks the run itself: a shell's `&` would start it with INT
+ * and QUIT ignored, which nothing inside can undo (an ignored signal stays
+ * ignored across exec), so a kill with either would reach nothing. Without
+ * `-f` (util-linux before 2.31, BusyBox) it falls back to `&`, where INT and
+ * QUIT still reach nothing, as in the Python SDK.
+ */
+export declare function startScript(runId: string, command: string, limitSec: number | null, unbuffered?: boolean): string;
+/**
+ * Report a run's state and the next slice of each stream. Prints three lines:
+ *
+ *   prized-run <running|done|gone|missing> <exit code|-> <stdout bytes> <stderr bytes> <timed out 0|1> <duration ms|->
+ *   <base64 of stdout from outOffset, at most maxChunk bytes>
+ *   <base64 of stderr from errOffset, at most maxChunk bytes>
+ *
+ * The state is read before the sizes, so a `done` report's sizes are final.
+ * Read-only: safe to repeat.
+ */
+export declare function pollScript(runId: string, outOffset: number, errOffset: number, maxChunk: number): string;
+/** Signal names kill() accepts (with or without the SIG prefix). */
+export declare const SIGNALS: Set<string>;
+/**
+ * Signal the run's whole process group. Exit 0 sent, 3 no such run, 4
+ * nothing left to signal: the run has ended.
+ *
+ * The group is named after the run's wrapper. Once the run has written its
+ * exit code it has ended, and nothing is sent (its wrapper may live a moment
+ * longer). While the wrapper's pid is alive, it must still be the wrapper
+ * (its command line names this run): a live process without it reused the
+ * pid once the run had ended (or been killed), its group is not this run's,
+ * and nothing is sent. Once the wrapper is gone, nothing proves the group
+ * is this run's any more.
+ */
+export declare function killScript(runId: string, signal: string): string;
+/**
+ * Remove a run's files once it has ended. A run still going keeps them
+ * (exit 5): its time limit's watchdog works from that directory, and so
+ * does every later status, wait or kill. Still going is what a status reads:
+ * no exit code yet, and the run's wrapper alive and still the run's. A pid
+ * or process group id reused since (after a restart of the sandbox, say)
+ * keeps nothing, or the files would never go; nor does what is left of the
+ * group once the wrapper is gone, which kill() no longer reaches either (a
+ * watchdog left in it still ends it at the time limit, even once the
+ * directory is gone). The directory itself stays, empty but for `cleaned`: it is
+ * what makes a start of the same run id start nothing, so a delayed resend
+ * of the start never runs the command twice. Not forever: each cleanup
+ * also removes the run directories marked `cleaned` more than
+ * CLEANED_KEEP_MIN minutes ago, and those left empty as long (by a start
+ * that never began), never one with a run's files in it.
+ */
+export declare function cleanupScript(runId: string): string;
+/**
+ * Stop a run whose start may or may not have happened (its answer was
+ * lost, or the caller left mid-start). If the run directory does not exist,
+ * make it, marked `cleaned`: a start of this run id that arrives later then
+ * finds it and starts nothing, and an abandon sent again knows it at once.
+ * If it exists, wait for the pid (the start writes it within its own ten
+ * seconds) and KILL the run's group. The directory is kept for the same
+ * reason, marked `cleaned`. Exit 0: the run can no longer
+ * start, was killed with its group, or had already ended. Exit 3: a start
+ * made the directory, but no pid came within ten seconds, so its command
+ * may yet run; nothing is marked. Safe to repeat.
+ */
+export declare function abandonScript(runId: string): string;
+/**
+ * List a directory, one NUL-terminated record per entry:
+ * `<type>\t<size>\t<mode>\t<mtime>\t<name>`. Exit 20 not a directory, 21 missing.
+ */
+export declare function listScript(path: string): string;
+/** Exit 0 when the path exists (a dangling link counts), 1 when it does not. */
+export declare function existsScript(path: string): string;
+/** Remove a path. Missing is not an error. */
+export declare function removeScript(path: string, recursive: boolean): string;

package/dist/esm/shell.js

@@ -0,0 +1,379 @@
+// Shell text the SDK sends as commands. Everything a caller supplies is
+// quoted with shellQuote; nothing else is interpolated but numbers and ids
+// the SDK made itself.
+/** One argument, quoted for a POSIX shell: as Python's shlex.quote does, so both SDKs send the same text. */
+export function shellQuote(value) {
+    if (value === '')
+        return "''";
+    if (/^[A-Za-z0-9_\/.,:=@%+-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+/** A command as one string: a string is passed through, an argv array is quoted. */
+export function commandText(command) {
+    if (typeof command === 'string')
+        return command;
+    if (command.length === 0)
+        return '';
+    return command.map(shellQuote).join(' ');
+}
+/** The template's working directory: where relative paths and commands start. */
+export const WORKSPACE_DIR = '/home/prized/work';
+/** A path as the sandbox reads it: relative paths start in the workspace. */
+export function sandboxPath(path) {
+    if (path === '')
+        return WORKSPACE_DIR;
+    return path.startsWith('/') ? path : `${WORKSPACE_DIR}/${path.replace(/^\.\/+/, '')}`;
+}
+// ---------------------------------------------------------------------------
+// Background commands. Each run gets a directory under the sandbox user's
+// home, at a fixed path (a command's own HOME does not move it):
+//
+//   ~/.prized/runs/<run id>/pid       the run's process group id
+//   ~/.prized/runs/<run id>/stdout    everything it printed, as it prints it
+//   ~/.prized/runs/<run id>/stderr
+//   ~/.prized/runs/<run id>/start     when it started, epoch ms
+//   ~/.prized/runs/<run id>/end       when it ended, epoch ms
+//   ~/.prized/runs/<run id>/exit      its exit code, once it has one
+//   ~/.prized/runs/<run id>/timedout  present when its time limit stopped it
+//   ~/.prized/runs/<run id>/watchdog  the time limit's pid, when it has one
+//   ~/.prized/runs/<run id>/limit     claimed once, by the limit or the command's end
+//   ~/.prized/runs/<run id>/cleaned   all that is left once cleanup() ran
+//
+// The command runs in its own session (setsid), and what it starts stays in
+// that one process group with the time-limit watchdog, unless it leaves it
+// (setsid, a daemon): a kill reaches the group while the run lives, not a
+// process that left it. The scripts are the Python SDK's (sdk/python
+// src/prized/_runs.py), so either SDK can read a run the other started.
+export const RUNS_DIR = '/home/prized/.prized/runs';
+export const RUN_ID_RE = /^run_[0-9a-f]{16}$/;
+/**
+ * Minutes (by the sandbox's clock) a cleaned or abandoned run's directory
+ * stays: what keeps a resend of its start from running the command again.
+ * The SDK stops resending a start within minutes, so an hour is ample; each
+ * cleanup then removes the ones older than that, so they never pile up.
+ */
+export const CLEANED_KEEP_MIN = 60;
+/** The start script's exit when it launched the command but no pid came within ten seconds: it may yet run. */
+export const NO_PID_EXIT = 99;
+/**
+ * The longest time limit a start script renders, in seconds (about 31
+ * years): a longer one is none in all but name, and past 2^63 the shell's
+ * arithmetic would wrap it negative and stop the command at once.
+ */
+export const MAX_LIMIT_SEC = 1_000_000_000;
+/**
+ * The script that runs inside the run's session. Positional: $1 the run
+ * directory, $2 the shell, $3 the command, $4 the time limit in whole
+ * seconds ('' for none). No single quotes: it travels inside them.
+ *
+ * A signal sent to the run (HUP, INT, QUIT, TERM) does not end the wrapper,
+ * so it always writes `exit`: one that arrives before the launch means the
+ * command does not start (bar a window of microseconds just before the
+ * fork, where it reaches only the wrapper), and the run ends with that
+ * signal's 128+n code. One that arrives while the command runs reaches the
+ * command itself, in the same process group. USR1 and USR2 are the
+ * command's own to use.
+ *
+ * The caller's PATH (PRIZED_RUN_PATH, from the start script) is the
+ * command's alone: the wrapper and its watchdog keep the launcher's.
+ *
+ * The rest of the caller's env reaches the command as it was. A shell
+ * variable that came from the environment stays exported, so an assignment
+ * to it changes what every child is given: the scripts' own variables are
+ * __pz_ names (a caller's `d` once reached the command as the run's
+ * directory), and the scripts that lead to the command unset theirs first,
+ * so none is exported. Treat the prefix as theirs: a caller's variable
+ * named like one of the start script's or the wrapper's does not reach the
+ * command.
+ *
+ * The limit is a watchdog in the same process group, not timeout(1):
+ * timeout moves the command into a process group of its own, out of reach
+ * of a kill sent to the run. It ignores HUP, INT, QUIT, TERM, USR1 and USR2
+ * (so a kill of the run does not stop it first), checks once a second,
+ * writes `timedout`, sends TERM to the group, and five seconds later KILL to
+ * whatever is left of it. The limit and the command's end race, so `limit`
+ * is claimed once, by whichever comes first (mkdir is atomic): an end that
+ * came first stops the watchdog (only while its pid is still the
+ * watchdog's), and a limit that fired first is left to finish.
+ *
+ * Kept equal to the Python SDK's _WRAPPER (test/run-scripts.test.ts).
+ */
+export const WRAPPER = [
+    'unset __pz_k __pz_u __pz_w __pz_c __pz_end',
+    '__pz_k=',
+    'trap "__pz_k=129" HUP',
+    'trap "__pz_k=130" INT',
+    'trap "__pz_k=131" QUIT',
+    'trap "__pz_k=143" TERM',
+    // A signal the command may use for itself must not end the wrapper.
+    'trap ":" USR1 USR2',
+    // The caller's PATH is the command's alone; the wrapper keeps its own.
+    '__pz_u="${PRIZED_RUN_PATH-$PATH}"',
+    'unset PRIZED_RUN_PATH',
+    // No published pid, no run: nothing could stop it.
+    'echo "$$" > "$1/pid" || exit 1',
+    'date +%s%3N > "$1/start"',
+    '__pz_w=',
+    'if [ -n "$4" ]; then',
+    '  ( trap "" HUP INT QUIT TERM USR1 USR2',
+    // date, not bash's SECONDS: under /bin/sh (dash) SECONDS is unset and the
+    // limit would never fire.
+    '    __pz_end=$(($(date +%s) + $4 + 1))',
+    '    while [ ! -e "$1/exit" ]; do',
+    '      if [ "$(date +%s)" -ge "$__pz_end" ]; then',
+    // The limit and the command's end race: `limit` is claimed once, by
+    // whichever comes first (mkdir is atomic). An end that came first stops
+    // the watchdog; a limit that fired first is left to finish. Taken
+    // already means the command ended first; a mkdir that failed for want of
+    // disk claims nothing, and the limit still applies, as it does once the
+    // directory itself is gone (`true`, not `:`: under dash a failed
+    // redirection on a special builtin ends the subshell before its KILL).
+    '        mkdir "$1/limit" 2> /dev/null || [ ! -d "$1/limit" ] || exit 0',
+    '        true > "$1/timedout"',
+    '        kill -s TERM -- "-$$"',
+    // Always the full grace, then KILL: the command's shell may be gone while
+    // a child that ignores TERM is still running. The KILL takes the watchdog
+    // too; it is the last thing in the group.
+    '        sleep 5',
+    '        kill -s KILL -- "-$$"',
+    '        exit 0',
+    '      fi',
+    '      sleep 1',
+    '    done ) > /dev/null 2>&1 < /dev/null &',
+    '  __pz_w=$!',
+    '  echo "$__pz_w" > "$1/watchdog"',
+    'fi',
+    'if [ -n "$__pz_k" ]; then __pz_c=$__pz_k; else',
+    'PATH="$__pz_u" "$2" -c "$3" > "$1/stdout" 2> "$1/stderr" < /dev/null',
+    '__pz_c=$?',
+    'fi',
+    // The command ended within its limit: the limit no longer applies to
+    // anything it left running, so the watchdog is stopped before `exit`
+    // exists (no reader can delete the run while it waits to fire). A limit
+    // that already fired is left to finish: its KILL is what stops children
+    // that ignored the TERM.
+    'if [ -n "$__pz_w" ] && { mkdir "$1/limit" 2> /dev/null || [ ! -d "$1/limit" ]; }; then ' +
+        // Only the watchdog itself (a subshell: it has the wrapper's command
+        // line): a pid it no longer holds is not signalled.
+        `${isRun('$__pz_w', '"prized-run $1 "')} ` +
+        '&& kill -s KILL "$__pz_w" 2> /dev/null; wait "$__pz_w" 2> /dev/null; fi',
+    'date +%s%3N > "$1/end"',
+    'echo "$__pz_c" > "$1/exit.tmp" && mv -f "$1/exit.tmp" "$1/exit"',
+].join('\n');
+/** The PATH the start script launches with, whatever the caller's env says. */
+export const LAUNCH_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+/**
+ * Start `command` detached. Prints the run's process group id. Safe to send
+ * twice with the same run id: the second send finds the directory and prints
+ * the first one's pid instead of starting it again.
+ *
+ * The caller's PATH reaches the command through the environment
+ * (PRIZED_RUN_PATH, not an argument, which every user of the guest could
+ * read); the launcher itself runs on LAUNCH_PATH, so a PATH of the
+ * caller's never hides setsid or the shell from it.
+ *
+ * `unbuffered` (background and streamed commands, whose output is read as
+ * it is printed) sets PYTHONUNBUFFERED=1 unless the command's environment
+ * already has it: Python's output to a file is otherwise held in a buffer
+ * until it exits.
+ *
+ * `setsid -f` forks the run itself: a shell's `&` would start it with INT
+ * and QUIT ignored, which nothing inside can undo (an ignored signal stays
+ * ignored across exec), so a kill with either would reach nothing. Without
+ * `-f` (util-linux before 2.31, BusyBox) it falls back to `&`, where INT and
+ * QUIT still reach nothing, as in the Python SDK.
+ */
+export function startScript(runId, command, limitSec, unbuffered = false) {
+    const limit = limitSec === null ? "''" : String(Math.min(Math.max(1, Math.ceil(limitSec)), MAX_LIMIT_SEC));
+    const run = `prized-run "$__pz_d" "$__pz_s" ${shellQuote(command)} ${limit} > /dev/null 2>&1 < /dev/null`;
+    return [
+        // The caller's env goes to the command as it is (see WRAPPER).
+        'unset __pz_r __pz_d __pz_s __pz_w __pz_n',
+        'export PRIZED_RUN_PATH="${PATH-}"',
+        `PATH=${LAUNCH_PATH}`,
+        ...(unbuffered ? ['export PYTHONUNBUFFERED="${PYTHONUNBUFFERED-1}"'] : []),
+        `__pz_r=${RUNS_DIR}; __pz_d="$__pz_r/${runId}"`,
+        `command -v setsid > /dev/null 2>&1 || { echo 'setsid is not installed in this sandbox' >&2; exit 97; }`,
+        'mkdir -p "$__pz_r" || exit 98',
+        'if mkdir "$__pz_d" 2> /dev/null; then',
+        '  __pz_s=/bin/bash; [ -x "$__pz_s" ] || __pz_s=/bin/sh',
+        `  __pz_w='${WRAPPER}'`,
+        '  if setsid -f true > /dev/null 2>&1; then',
+        `    setsid -f "$__pz_s" -c "$__pz_w" ${run}`,
+        '  else',
+        `    setsid "$__pz_s" -c "$__pz_w" ${run} &`,
+        '  fi',
+        'fi',
+        `if [ -f "$__pz_d/cleaned" ]; then echo 'this run was already cleaned up' >&2; exit 96; fi`,
+        '__pz_n=0',
+        'while [ ! -s "$__pz_d/pid" ]; do',
+        '  __pz_n=$((__pz_n + 1))',
+        `  if [ "$__pz_n" -gt 200 ]; then echo 'the command did not start' >&2; exit ${NO_PID_EXIT}; fi`,
+        '  sleep 0.05',
+        'done',
+        'cat "$__pz_d/pid"',
+    ].join('\n');
+}
+/**
+ * A shell test: process `pid` (shell text) is a run's wrapper, or its
+ * watchdog (a subshell, with the wrapper's command line), not another
+ * process that reused the pid. The wrapper's arguments are `<shell> -c
+ * <wrapper> prized-run <run directory> ...`: its fourth and fifth must be
+ * exactly `expected` (shell text for "prized-run <run directory> "), not
+ * merely somewhere in its command line, where another run's command may
+ * name them too (`tail -f ~/.prized/runs/<id>/stdout`). /proc ends each
+ * argument with a NUL; here each is one line (a NUL becomes a newline, a
+ * newline a space).
+ */
+function isRun(pid, expected) {
+    return `[ "$(tr "\\0\\n" "\\n " < "/proc/${pid}/cmdline" 2> /dev/null | sed -n 4,5p | tr "\\n" " ")" = ${expected} ]`;
+}
+/** isRun for the run `runId`, whose pid is in $__pz_p. */
+function ours(runId) {
+    return isRun('$__pz_p', shellQuote(`prized-run ${RUNS_DIR}/${runId} `));
+}
+/**
+ * Report a run's state and the next slice of each stream. Prints three lines:
+ *
+ *   prized-run <running|done|gone|missing> <exit code|-> <stdout bytes> <stderr bytes> <timed out 0|1> <duration ms|->
+ *   <base64 of stdout from outOffset, at most maxChunk bytes>
+ *   <base64 of stderr from errOffset, at most maxChunk bytes>
+ *
+ * The state is read before the sizes, so a `done` report's sizes are final.
+ * Read-only: safe to repeat.
+ */
+export function pollScript(runId, outOffset, errOffset, maxChunk) {
+    const slice = (file, offset, size) => [
+        `__pz_n=$((${size} - ${offset})); [ "$__pz_n" -gt ${maxChunk} ] && __pz_n=${maxChunk}`,
+        `if [ "$__pz_n" -gt 0 ]; then tail -c +${offset + 1} "$__pz_d/${file}" | head -c "$__pz_n" | base64 -w 0; fi`,
+        'echo',
+    ];
+    return [
+        `__pz_d=${RUNS_DIR}/${runId}`,
+        'if [ ! -d "$__pz_d" ] || [ -f "$__pz_d/cleaned" ]; then echo "prized-run missing - 0 0 0 -"; exit 0; fi',
+        'if [ -f "$__pz_d/exit" ]; then __pz_st=done; __pz_c=$(cat "$__pz_d/exit")',
+        // Running while the run's wrapper lives and is still the run's, not
+        // another process that reused its pid once the run was killed.
+        `elif __pz_p=$(cat "$__pz_d/pid" 2> /dev/null) && [ -n "$__pz_p" ] && kill -0 "$__pz_p" 2> /dev/null && ${ours(runId)}; then __pz_st=running; __pz_c=-`,
+        'elif [ -f "$__pz_d/exit" ]; then __pz_st=done; __pz_c=$(cat "$__pz_d/exit")',
+        'else __pz_st=gone; __pz_c=-',
+        'fi',
+        '__pz_to=0; [ -e "$__pz_d/timedout" ] && __pz_to=1',
+        '__pz_du=-',
+        'if [ -f "$__pz_d/end" ]; then',
+        '  __pz_a=$(cat "$__pz_d/start" 2> /dev/null); __pz_b=$(cat "$__pz_d/end" 2> /dev/null)',
+        '  case "$__pz_a:$__pz_b" in *[!0-9:]* | :* | *:) ;; *) __pz_du=$((__pz_b - __pz_a)) ;; esac',
+        'fi',
+        '__pz_o=$(stat -c %s "$__pz_d/stdout" 2> /dev/null || echo 0)',
+        '__pz_e=$(stat -c %s "$__pz_d/stderr" 2> /dev/null || echo 0)',
+        'echo "prized-run $__pz_st $__pz_c $__pz_o $__pz_e $__pz_to $__pz_du"',
+        ...slice('stdout', outOffset, '$__pz_o'),
+        ...slice('stderr', errOffset, '$__pz_e'),
+    ].join('\n');
+}
+/** Signal names kill() accepts (with or without the SIG prefix). */
+export const SIGNALS = new Set(['TERM', 'KILL', 'INT', 'HUP', 'QUIT', 'USR1', 'USR2', 'STOP', 'CONT']);
+/**
+ * Signal the run's whole process group. Exit 0 sent, 3 no such run, 4
+ * nothing left to signal: the run has ended.
+ *
+ * The group is named after the run's wrapper. Once the run has written its
+ * exit code it has ended, and nothing is sent (its wrapper may live a moment
+ * longer). While the wrapper's pid is alive, it must still be the wrapper
+ * (its command line names this run): a live process without it reused the
+ * pid once the run had ended (or been killed), its group is not this run's,
+ * and nothing is sent. Once the wrapper is gone, nothing proves the group
+ * is this run's any more.
+ */
+export function killScript(runId, signal) {
+    const d = `${RUNS_DIR}/${runId}`;
+    return [
+        `__pz_p=$(cat ${d}/pid 2> /dev/null) && [ -n "$__pz_p" ] || exit 3`,
+        `[ ! -f ${d}/exit ] && kill -0 "$__pz_p" 2> /dev/null && ${ours(runId)} || exit 4`,
+        `kill -s ${signal} -- "-$__pz_p" 2> /dev/null || exit 4`,
+    ].join('\n');
+}
+/**
+ * Remove a run's files once it has ended. A run still going keeps them
+ * (exit 5): its time limit's watchdog works from that directory, and so
+ * does every later status, wait or kill. Still going is what a status reads:
+ * no exit code yet, and the run's wrapper alive and still the run's. A pid
+ * or process group id reused since (after a restart of the sandbox, say)
+ * keeps nothing, or the files would never go; nor does what is left of the
+ * group once the wrapper is gone, which kill() no longer reaches either (a
+ * watchdog left in it still ends it at the time limit, even once the
+ * directory is gone). The directory itself stays, empty but for `cleaned`: it is
+ * what makes a start of the same run id start nothing, so a delayed resend
+ * of the start never runs the command twice. Not forever: each cleanup
+ * also removes the run directories marked `cleaned` more than
+ * CLEANED_KEEP_MIN minutes ago, and those left empty as long (by a start
+ * that never began), never one with a run's files in it.
+ */
+export function cleanupScript(runId) {
+    const d = `${RUNS_DIR}/${runId}`;
+    return [
+        `if [ ! -f ${d}/exit ] && __pz_p=$(cat ${d}/pid 2> /dev/null) && [ -n "$__pz_p" ] && kill -0 "$__pz_p" 2> /dev/null && ${ours(runId)}; then exit 5; fi`,
+        `find ${RUNS_DIR} -mindepth 2 -maxdepth 2 -path '${RUNS_DIR}/run_*/cleaned' -mmin +${CLEANED_KEEP_MIN} -printf '%h\\0' 2> /dev/null | xargs -0 -r rm -rf --`,
+        `find ${RUNS_DIR} -mindepth 1 -maxdepth 1 -type d -name 'run_*' -empty -mmin +${CLEANED_KEEP_MIN} -delete 2> /dev/null`,
+        `[ -d ${d} ] || exit 0`,
+        `find ${d} -mindepth 1 -maxdepth 1 ! -name cleaned -exec rm -rf -- {} +`,
+        `: > ${d}/cleaned`,
+    ].join('\n');
+}
+/**
+ * Stop a run whose start may or may not have happened (its answer was
+ * lost, or the caller left mid-start). If the run directory does not exist,
+ * make it, marked `cleaned`: a start of this run id that arrives later then
+ * finds it and starts nothing, and an abandon sent again knows it at once.
+ * If it exists, wait for the pid (the start writes it within its own ten
+ * seconds) and KILL the run's group. The directory is kept for the same
+ * reason, marked `cleaned`. Exit 0: the run can no longer
+ * start, was killed with its group, or had already ended. Exit 3: a start
+ * made the directory, but no pid came within ten seconds, so its command
+ * may yet run; nothing is marked. Safe to repeat.
+ */
+export function abandonScript(runId) {
+    return [
+        `__pz_d=${RUNS_DIR}/${runId}`,
+        `mkdir -p ${RUNS_DIR} 2> /dev/null`,
+        'if { mkdir "$__pz_d" 2> /dev/null && true > "$__pz_d/cleaned"; } || [ -f "$__pz_d/cleaned" ]; then exit 0; fi',
+        '__pz_n=0',
+        'while [ ! -s "$__pz_d/pid" ]; do',
+        '  __pz_n=$((__pz_n + 1))',
+        '  if [ "$__pz_n" -gt 200 ]; then exit 3; fi',
+        '  sleep 0.05',
+        'done',
+        '__pz_p=$(cat "$__pz_d/pid")',
+        `if kill -0 "$__pz_p" 2> /dev/null && ${ours(runId)}; then kill -s KILL -- "-$__pz_p" 2> /dev/null; fi`,
+        // Its files go, its directory stays (marked `cleaned`): a start of
+        // this id that arrives later still starts nothing.
+        'find "$__pz_d" -mindepth 1 -maxdepth 1 ! -name cleaned -exec rm -rf -- {} +',
+        ': > "$__pz_d/cleaned"',
+        'exit 0',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Files the edge has no route for, done with a command.
+/**
+ * List a directory, one NUL-terminated record per entry:
+ * `<type>\t<size>\t<mode>\t<mtime>\t<name>`. Exit 20 not a directory, 21 missing.
+ */
+export function listScript(path) {
+    const p = shellQuote(path);
+    return [
+        `if [ ! -d ${p} ]; then if [ -e ${p} ] || [ -L ${p} ]; then exit 20; fi; exit 21; fi`,
+        // -H: a link given as the directory is followed (the -d test above
+        // already did); links inside it are listed as links, never followed.
+        `find -H ${p} -mindepth 1 -maxdepth 1 -printf '%y\\t%s\\t%M\\t%T@\\t%f\\0'`,
+    ].join('\n');
+}
+/** Exit 0 when the path exists (a dangling link counts), 1 when it does not. */
+export function existsScript(path) {
+    const p = shellQuote(path);
+    return `if [ -e ${p} ] || [ -L ${p} ]; then exit 0; fi; exit 1`;
+}
+/** Remove a path. Missing is not an error. */
+export function removeScript(path, recursive) {
+    return `rm ${recursive ? '-rf' : '-f'} -- ${shellQuote(path)}`;
+}

package/dist/esm/toolbox.d.ts

@@ -0,0 +1,48 @@
+import { type Config, type RetryMode } from './http.js';
+import { type Effect } from './outcome.js';
+import type { ExecResult } from './types.js';
+/** What the SDK needs to reach one sandbox's exec and files. */
+export interface Toolbox {
+    readonly config: Config;
+    readonly sandboxId: string;
+    /** `https://…/v1/sandbox/<id>`, re-read on every call. */
+    base(): string;
+}
+/** Each stream of one call keeps at most this many bytes. */
+export declare const MAX_OUTPUT_BYTES: number;
+/** One upload or download moves at most this many bytes. */
+export declare const MAX_FILE_BYTES: number;
+export interface RawExecRequest {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * ms. Always sent: the sandbox's own default (5 minutes) is exactly how
+     * long Node's fetch waits for an answer's headers, so a call that left it
+     * to the sandbox would fail at the very moment the command's answer came.
+     */
+    timeoutMs: number;
+}
+/** One command over the edge, answered when it finishes. */
+export declare function rawExec(toolbox: Toolbox, req: RawExecRequest, options: {
+    retry: RetryMode;
+    signal?: AbortSignal | undefined;
+    deadline?: number | undefined;
+    /** What the command does, for an error that says whether it happened (`exec`: a command unless given). */
+    effect?: Effect | undefined;
+}): Promise<ExecResult>;
+/** A helper command the SDK sends itself; a non-zero exit is the caller's to judge. */
+export declare function helperExec(toolbox: Toolbox, command: string, options?: {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number;
+    /**
+     * `safe` (the default) for helpers that may be repeated: read-only, or
+     * keyed by an id the SDK chose. A destructive helper (rm) passes `exec`,
+     * so a lost answer is never sent a second time.
+     */
+    retry?: RetryMode;
+    /** Epoch ms (config.now()) past which neither the attempt nor a retry may run. */
+    deadline?: number | undefined;
+    /** What a destructive helper does, for its errors (outcome.ts). */
+    effect?: Effect | undefined;
+}): Promise<ExecResult>;

package/dist/esm/toolbox.js

@@ -0,0 +1,83 @@
+// The exec/files edge for one sandbox: POST {base}/process/execute,
+// POST {base}/files/upload?path=, GET {base}/files/download?path=.
+import { PrizedError } from './errors.js';
+import { request } from './http.js';
+import { commandEffect, helperEffect, withOutcome } from './outcome.js';
+/** Each stream of one call keeps at most this many bytes. */
+export const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** One upload or download moves at most this many bytes. */
+export const MAX_FILE_BYTES = 100 * 1024 * 1024;
+/** Slack on top of a command's own timeout before the SDK stops waiting for the answer. */
+const EXEC_ANSWER_SLACK_MS = 30_000;
+/**
+ * How many of the stream's bytes the sandbox kept, from the text its answer
+ * carried. The sandbox keeps exactly the first MAX_OUTPUT_BYTES; each byte
+ * of that which was not valid UTF-8 arrives as one U+FFFD, so U+FFFD counts
+ * as one byte here, not the three it encodes to (as the Python SDK counts):
+ * 2 MiB of binary output is not a full stream.
+ */
+function keptBytes(text) {
+    // Fast path: fewer than MAX/3 UTF-16 units can never encode to MAX bytes.
+    if (text.length * 3 < MAX_OUTPUT_BYTES)
+        return text.length;
+    let replaced = 0;
+    for (let at = text.indexOf('\uFFFD'); at !== -1; at = text.indexOf('\uFFFD', at + 1))
+        replaced += 1;
+    return new TextEncoder().encode(text).length - 2 * replaced;
+}
+/** One command over the edge, answered when it finishes. */
+export async function rawExec(toolbox, req, options) {
+    if (!(req.timeoutMs > 0))
+        throw new PrizedError('invalid_argument', 'A command sent on one call needs a timeout > 0 ms');
+    const effect = options.effect ?? (options.retry === 'exec' ? commandEffect() : undefined);
+    const body = { command: req.command };
+    if (req.cwd !== undefined)
+        body.cwd = req.cwd;
+    if (req.env !== undefined && Object.keys(req.env).length > 0)
+        body.env = req.env;
+    body.timeout = req.timeoutMs / 1000;
+    const result = await request(toolbox.config, {
+        method: 'POST',
+        url: `${toolbox.base()}/process/execute`,
+        json: body,
+        retry: options.retry,
+        timeoutMs: req.timeoutMs + EXEC_ANSWER_SLACK_MS,
+        signal: options.signal,
+        deadline: options.deadline,
+        sandboxId: toolbox.sandboxId,
+        ...(effect === undefined ? {} : { effect }),
+    });
+    const doc = result.json;
+    if (doc === null || typeof doc !== 'object' || typeof doc.exitCode !== 'number') {
+        const unread = new PrizedError('bad_response', 'The exec answer carried no exit code.', {
+            status: result.status,
+            sandboxId: toolbox.sandboxId,
+        });
+        // A 2xx: the command ran, whatever its answer lacks.
+        throw effect === undefined ? unread : withOutcome(unread, effect, 'did');
+    }
+    const stdout = typeof doc.stdout === 'string' ? doc.stdout : '';
+    const stderr = typeof doc.stderr === 'string' ? doc.stderr : '';
+    const truncated = keptBytes(stdout) >= MAX_OUTPUT_BYTES || keptBytes(stderr) >= MAX_OUTPUT_BYTES;
+    return {
+        stdout,
+        stderr,
+        exitCode: doc.exitCode,
+        durationMs: typeof doc.durationMs === 'number' ? doc.durationMs : 0,
+        timedOut: doc.timedOut === true,
+        truncated,
+        ...(truncated ? { truncatedReason: 'output_limit' } : {}),
+    };
+}
+/** A helper command the SDK sends itself; a non-zero exit is the caller's to judge. */
+export function helperExec(toolbox, command, options = {}) {
+    const retry = options.retry ?? 'safe';
+    return rawExec(toolbox, { command, timeoutMs: options.timeoutMs ?? 60_000 }, {
+        retry,
+        signal: options.signal,
+        deadline: options.deadline,
+        // Not the caller's command: an `exec` helper that names no effect (a
+        // kill) gets words that claim nothing about what it does.
+        effect: options.effect ?? (retry === 'exec' ? helperEffect() : undefined),
+    });
+}