@struktoai/mirage-core/dist/runtime/sandbox/constants.d.ts

A Unified Virtual Filesystem For AI Agents

import type { ProcessHandle } from '../../process/handle.ts';
import type { MountType } from '../types.ts';
/**
 * Why a sandbox cannot take a line, named by the state its status command
 * reported. `hints` holds the provider's advice per state, with `{name}`
 * standing for `name`; `otherwise` is the advice for a state it lacks.
 * Mirrors Python's `not_running_hint`.
 */
export declare function notRunningHint(noun: string, name: string, state: string, hints: Readonly<Record<string, string>>, otherwise?: string | null): string;
/**
 * The signal a `kill` stopped `runner` with, when a program may handle it:
 * null for KILL, or for a run no `kill` stopped, which is killed at once.
 * Mirrors Python's `stop_signal`.
 */
export declare function stopSignal(runner: ProcessHandle | null): number | null;
export declare const MOUNT_TYPES: readonly MountType[];
export declare const MOUNT_WAIT_SECONDS = 15;
export declare const MOUNT_POLL_SECONDS = 0.1;
export declare const UNMOUNT_WAIT_SECONDS = 5;
export declare const PIPE_DIAGNOSTIC_BYTES = 16384;
export declare const PIPE_DIAGNOSTIC_WAIT_SECONDS = 1;
export declare const SSHFS_OPTIONS = "passive,dir_cache=no,direct_io,attr_timeout=0,entry_timeout=0,negative_timeout=0";
export declare const SSHFS_LOG_PREFIX = "/tmp/.mirage_sshfs";
export declare const SSHFS_HINT = "serving the workspace into a sandbox needs sshfs there; install it in the image (apt-get install sshfs)";
export declare const PIPE_SERVER_HINT = "serving the workspace into a sandbox needs @struktoai/mirage-node and its ssh2 peer";
/**
 * Every argv a sandbox runs goes under this POSIX sh prelude, with the
 * cwd as $1: a provider program's exec passes `-w /` (`execArgs`), and a
 * provider whose exec takes one command line dresses it (`wrapLine`), so
 * no provider's own cwd is used. An exec's `-e` can append to the image's
 * environment rather than replace a name it already sets, `-w` can
 * create a missing directory, and an SDK's cwd fails a missing one its
 * own way (E2B: exit 1). sh imports the environment last-wins, `cd`
 * fails loud (126) on a cwd the sandbox does not serve, and `exec` hands
 * over the argv unchanged. `cd` runs without CDPATH, so a relative cwd
 * resolves from `/` and prints nothing, while the program still sees the
 * guest's own CDPATH. The shell is named by path, /bin/sh, since the
 * command's PATH is the session's and may hold no sh; the argv after the
 * prelude is still found on it.
 */
export declare const EXEC_PRELUDE = "CDPATH= cd -- \"$1\" || exit 126; shift; exec \"$@\"";
/**
 * Every process a run starts in a sandbox carries this variable, set to the
 * run's own id, so a run cancelled midway can be stopped in the box:
 * stopping the client that started it does not reach the box everywhere
 * (`docker exec` has no kill, and the daemon keeps draining the program's
 * output, so a `yes` cut short by `head` would spin on). The id rides the
 * environment because every process of a pipeline inherits it.
 */
export declare const EXEC_ID = "MIRAGE_EXEC_ID";
export declare const REAP_WAIT_SECONDS = 5;
export declare const STOP_GRACE_SECONDS = 1;
export declare const HOST_START_SLACK_SECONDS = 2;
export declare const STOP_POLL_SECONDS = 0.02;
export declare const REAP_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
/**
 * The command line for a sandbox whose exec takes one (ssh, e2b,
 * daytona): cwd, env, then the argv.
 *
 * Such an exec has no docker-style `-w`/`-e` to trust: SSH's env channel
 * is AcceptEnv-gated server-side, so it silently drops names, and an
 * SDK's own cwd fails a missing directory in its own words. So the
 * working directory and the merged environment ride the command itself:
 * the prelude every sandbox runs a command under enters `cwd` (exit 126
 * when the sandbox lacks it), then `env 'K=V' ... 'prog' 'arg'`; a shell
 * line is the argv `/bin/sh -c line`. Every piece is single-quoted for sh,
 * so the shell the exec starts reads each as one word whatever it holds;
 * the sandbox only needs a POSIX shell at `/bin/sh`.
 *
 * @param argv the program and its arguments.
 * @param env the merged environment.
 * @param cwd the working directory, passed through verbatim.
 */
export declare function wrapLine(argv: readonly string[], env: Record<string, string>, cwd: string): string;
export declare const REAP_ABSENT = 3;
/**
 * The shell line that stops every process of the run `execId`.
 *
 * Each process whose environment holds the run's id, found through
 * `/proc`, gets `signum`, and what still runs a second later gets KILL,
 * so a program that ignores it stops too. The line exits 0 once it stopped
 * them and `REAP_ABSENT` when there were none. It looks grep up on its own
 * PATH (`REAP_PATH`) and exits 127 without it, so it needs only a POSIX
 * shell, grep and `/proc`.
 *
 * @param execId the run's id, as `EXEC_ID` carries it.
 * @param signum the first signal, TERM (15) unless a `kill` named another.
 */
export declare function reapLine(execId: string, signum?: number): string;
export declare const FAKETIME_PROBE_SECONDS = 30;
export declare const FAKETIME_LIBRARIES: string[];
/**
 * What has a process read the running workspace's system time through the
 * libfaketime at `library`: the time now, in epoch seconds to the
 * millisecond, which its clock and its children's run on from, whatever
 * the machine's own clock or zone; the monotonic clock and file dates, which
 * the workspace already gives, left alone. `env`'s
 * `LD_PRELOAD` libraries load after it. Empty when the workspace keeps the
 * host's time. Mirrors Python's `faketime_env`.
 */
export declare function faketimeEnv(library: string, env: Record<string, string>): Record<string, string>;
/**
 * A shell line that prints the first of `FAKETIME_LIBRARIES` a sandbox
 * holds, and nothing when it holds none. Mirrors Python's `faketime_probe`.
 */
export declare function faketimeProbe(): string;
//# sourceMappingURL=constants.d.ts.map