@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/microsandbox/runtime.d.ts

@@ -0,0 +1,793 @@
+import { Buffer } from "node:buffer";
+import type { AsyncExecStartResult, AsyncExecStatus, ExecOptions, ExecResult, LaunchOptions, RuntimeCapabilities, RuntimeHandle, WorkflowRuntime } from "../types.js";
+import type { AsyncRunStartResult, AsyncRunStatus, RunScriptResult, SandboxCountOptions, SandboxLookupOptions, SandboxRuntime } from "../port.js";
+/**
+ * Admit one async run.
+ *
+ * Arguments: `$1` command, `$2` run directory, `$3` its parent, `$4` shell.
+ *
+ * Prints exactly one of:
+ *  - `ADMITTED <pid>` — this call created the run.
+ *  - `CLAIMED <pid>`  — the session was already admitted for THIS EXACT
+ *    command, so its existing run is adopted. This is the outcome-unknown
+ *    case: a submit whose response was lost is retried by the caller and
+ *    resolves here, without ever starting a second process.
+ *  - `CONFLICT`       — the session is already admitted for a DIFFERENT
+ *    command (or its record is unreadable). Nothing is started and nothing is
+ *    overwritten; the caller gets a typed error.
+ *
+ * @internal Exported only so the protocol tests can execute it under a real
+ * `/bin/sh`. Not part of the package's public API.
+ */
+export declare const MICROSANDBOX_RUN_ADMIT_SCRIPT: string;
+/**
+ * Report one async run's outcome.
+ *
+ * Argument: `$1` run directory. Prints exactly one of `EXIT <code>`,
+ * `RUNNING`, `MISSING`, `UNKNOWN <reason>`, or `LOST <reason>`.
+ *
+ * The exit file is checked first and again last: the wrapper writes it as its
+ * final act, so re-reading after the liveness probe closes the window where a
+ * run finishes mid-probe and would otherwise read as lost.
+ *
+ * LIVENESS IS THREE CHECKS, not one, because each answers a different way of
+ * losing a run:
+ *  - boot id, for "the sandbox restarted underneath it";
+ *  - `kill -0`, for "the process is gone";
+ *  - START TIME, for "the pid is alive but it is somebody else's now". Without
+ *    the third, a recycled pid reports RUNNING forever, which is the one
+ *    failure a poll loop cannot end on.
+ *
+ * FALLBACK, stated because it is a real reduction in what the probe can tell
+ * apart: when the guest has no procfs, admission records no start time and the
+ * probe degrades to boot id + pid liveness — exactly the behaviour before start
+ * time existed. The fallback is chosen by the ABSENCE of a recorded start time,
+ * never by a failure to read the current one: if a start time was recorded and
+ * the current read fails while the pid is alive, the probe emits an explicit
+ * UNKNOWN marker. That is neither proof of continued life nor proof of pid
+ * reuse, so the adapter turns it into a retryable status-probe error.
+ *
+ * @internal Exported only for the protocol tests (see above).
+ */
+export declare const MICROSANDBOX_RUN_STATUS_SCRIPT: string;
+/**
+ * Read one run's captured output.
+ *
+ * Arguments: `$1` log path, `$2` byte cap. Exits 0 with the last `$2` bytes of
+ * the file, or 0 with NO output when the file is genuinely absent; any other
+ * failure exits non-zero.
+ *
+ * THE EXIT CODE IS THE WHOLE POINT. The previous form of this read was
+ * `tail -c N path 2>/dev/null || true`, which flattened three different
+ * situations — "the run has not written anything yet", "the log is
+ * unreadable", and "the guest call failed" — onto the same empty string. Empty
+ * output is a legitimate answer for a run that printed nothing, so a caller
+ * cannot tell that reading from an unreadable one. Absence is now the ONLY
+ * condition that yields empty-and-successful; everything else fails loudly and
+ * the adapter raises {@link MicrosandboxLogReadError}.
+ *
+ * The cap is read as one byte MORE than the caller's limit, so the adapter can
+ * see that a longer file exists and report `truncated` rather than handing back
+ * a tail that reads like a complete log.
+ *
+ * @internal Exported only for the protocol tests (see above).
+ */
+export declare const MICROSANDBOX_RUN_LOG_SCRIPT: string;
+/** `SandboxStatus` — the SDK's own status vocabulary. */
+export type MicrosandboxStatus = "running" | "stopped" | "crashed" | "draining";
+type MsbExecOutput = {
+    readonly code: number;
+    readonly success: boolean;
+    stdout(): string;
+    stderr(): string;
+};
+type MsbExecOptionsBuilder = {
+    args(args: string[]): MsbExecOptionsBuilder;
+    cwd(cwd: string): MsbExecOptionsBuilder;
+    envs(vars: Record<string, string>): MsbExecOptionsBuilder;
+    timeout(ms: number): MsbExecOptionsBuilder;
+    tty(enabled: boolean): MsbExecOptionsBuilder;
+};
+type MsbFsOps = {
+    write(path: string, data: Uint8Array | string): Promise<void>;
+    read(path: string): Promise<Uint8Array>;
+    readToString(path: string): Promise<string>;
+    mkdir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    copyFromHost(hostPath: string, guestPath: string): Promise<void>;
+    copyToHost(guestPath: string, hostPath: string): Promise<void>;
+};
+type MsbSandbox = {
+    readonly name: string;
+    exec(cmd: string, args?: Iterable<string>): Promise<MsbExecOutput>;
+    execWith(cmd: string, configure: (b: MsbExecOptionsBuilder) => MsbExecOptionsBuilder): Promise<MsbExecOutput>;
+    fs(): MsbFsOps;
+    detach?(): Promise<void>;
+};
+type MsbSandboxHandle = {
+    readonly name: string;
+    readonly status: MicrosandboxStatus;
+    readonly createdAt?: Date | null;
+    readonly updatedAt?: Date | null;
+    connect(): Promise<MsbSandbox>;
+    connectWithTimeout(timeoutMs: number): Promise<MsbSandbox>;
+    start(): Promise<MsbSandbox>;
+    startDetached(): Promise<MsbSandbox>;
+    stop(): Promise<void>;
+    kill(): Promise<void>;
+    remove(): Promise<void>;
+};
+type MsbSandboxPage = {
+    sandboxes: MsbSandboxHandle[];
+    nextCursor?: string;
+};
+type MsbSandboxListBuilder = {
+    limit(limit: number): MsbSandboxListBuilder;
+    cursor(cursor: string): MsbSandboxListBuilder;
+    labels(labels: Record<string, string>): MsbSandboxListBuilder;
+};
+type MsbSandboxBuilder = {
+    image(image: string): MsbSandboxBuilder;
+    fromSnapshot(pathOrName: string): MsbSandboxBuilder;
+    cpus(n: number): MsbSandboxBuilder;
+    memory(mib: number): MsbSandboxBuilder;
+    workdir(path: string): MsbSandboxBuilder;
+    envs(vars: Record<string, string>): MsbSandboxBuilder;
+    labels(labels: Record<string, string>): MsbSandboxBuilder;
+    detached(enabled: boolean): MsbSandboxBuilder;
+    idleTimeout(secs: number): MsbSandboxBuilder;
+    maxDuration(secs: number): MsbSandboxBuilder;
+    replace(): MsbSandboxBuilder;
+    create(): Promise<MsbSandbox>;
+};
+type MsbSandboxStatics = {
+    builder(name: string): MsbSandboxBuilder;
+    get(name: string): Promise<MsbSandboxHandle | null>;
+    listWith(configure: (b: MsbSandboxListBuilder) => MsbSandboxListBuilder): Promise<MsbSandboxPage>;
+};
+/**
+ * The slice of the `microsandbox` module this adapter binds to.
+ *
+ * Exported so a consumer can supply a double (tests, a proxy that adds
+ * tracing) through {@link MicrosandboxRuntimeOptions.sdk} without depending on
+ * the SDK's internal type graph.
+ */
+export type MicrosandboxSdk = {
+    Sandbox: MsbSandboxStatics;
+    withDefaultBackend<T>(backend: MicrosandboxBackend, fn: () => Promise<T> | T): Promise<T>;
+};
+/**
+ * Backend routing for one runtime instance — mirrors the SDK's
+ * `DefaultBackend`.
+ *
+ * There is deliberately no default: `"local"` would silently run workloads on
+ * the caller's host, and a cloud URL is deployment-specific. The API key is
+ * accepted here as a value the caller supplies at construction from its own
+ * secret store; this package never reads an environment variable, never logs
+ * the key, and never writes it to disk.
+ */
+export type MicrosandboxBackend = "local" | {
+    kind: "cloud";
+    /** Hosted API endpoint. Omit to use the SDK's own default endpoint. */
+    url?: string;
+    apiKey: string;
+} | {
+    kind: "cloud";
+    profile: string;
+};
+export type MicrosandboxRuntimeOptions = {
+    /**
+     * Backend this runtime routes every SDK call through. Required: see
+     * {@link MicrosandboxBackend}.
+     */
+    backend: MicrosandboxBackend;
+    /**
+     * OCI image to boot. Required unless {@link snapshot} is given: images are
+     * registry- and consumer-specific, so no default is correct for anyone else.
+     */
+    image?: string;
+    /**
+     * Snapshot to boot from instead of an image. Mutually exclusive with
+     * {@link image}.
+     */
+    snapshot?: string;
+    /**
+     * Home directory inside the guest, reported by `getHomeDir`. Required: it is
+     * a property of the image, which this package does not choose.
+     */
+    homeDir: string;
+    /** Default working directory for launched sandboxes. */
+    workdir?: string;
+    /** vCPU count applied at create time. Omit to accept the image default. */
+    cpus?: number;
+    /** Guest memory in MiB applied at create time. */
+    memoryMiB?: number;
+    /** Idle-shutdown budget in seconds, applied at create time. */
+    idleTimeoutSeconds?: number;
+    /** Hard sandbox lifetime in seconds, applied at create time. */
+    maxDurationSeconds?: number;
+    /**
+     * Replace a same-named sandbox at create time. Defaults to `false`: names are
+     * the identity here, so replacing on collision would destroy a sandbox this
+     * caller may not own.
+     */
+    replaceExisting?: boolean;
+    /** Prefix for generated sandbox names when the caller supplies none. */
+    namePrefix?: string;
+    /** Guest directory holding async-run state files. Defaults to `/tmp/microsandbox-run`. */
+    runStateDir?: string;
+    /** Shell used to interpret command strings. Defaults to `/bin/sh`. */
+    shell?: string;
+    /** Timeout for `connect` to an already-running sandbox. Defaults to 10s. */
+    connectTimeoutMs?: number;
+    /**
+     * Deadline for a whole label lookup, including every page it drains.
+     * Defaults to 10s, and is overridden per call by `options.timeoutMs`.
+     */
+    lookupTimeoutMs?: number;
+    /** Page size used when draining label listings. Defaults to 100. */
+    listPageSize?: number;
+    /**
+     * How long a call may wait for the process-global backend gate before failing
+     * with {@link MicrosandboxBackendBusyError}. Defaults to 30s.
+     *
+     * Only meaningful in a process that drives MORE THAN ONE backend: a process
+     * on a single backend shares one open scope and never queues.
+     */
+    backendQueueTimeoutMs?: number;
+    /** Injection seam for tests / a wrapping adapter — defaults to lazy `import("microsandbox")`. */
+    sdk?: MicrosandboxSdk;
+    /**
+     * Called when the reclamation of a late-succeeded create — the one triggered
+     * by `MicrosandboxCreateTimeoutError` — could not tear the sandbox down.
+     *
+     * The reclamation path used to swallow every error silently, on the theory
+     * that a leaked microVM is at worst best-effort waste. It is not: a
+     * silently swallowed teardown is a leak that no downstream observer can see
+     * or bill, which is exactly the failure mode PR #10 was blocked on. Now the
+     * silent catch is replaced by this hook, called synchronously with the
+     * sandbox NAME (never argv, never a secret) and the underlying error, so
+     * consumers can log, page, or re-queue an operator cleanup. The reclamation
+     * promise still resolves — the caller of `launch` already has its typed
+     * timeout error, and throwing here would produce an unhandled rejection
+     * on a promise the caller cannot await.
+     *
+     * The hook is CALLED SYNCHRONOUSLY inside the reclamation's async catch,
+     * so it must not throw or the runtime will emit an unhandled rejection. Any
+     * async follow-up (log flush, alert dispatch) should be scheduled by the
+     * hook and awaited elsewhere.
+     */
+    onReclaimFailure?: (sandboxName: string, error: unknown) => void;
+};
+/**
+ * A sandbox name exceeded the SDK's 128 UTF-8 byte cap.
+ *
+ * Raised instead of truncating: the name IS the identity, so a truncated name
+ * would collide two distinct sandboxes onto one addressable handle.
+ */
+export declare class MicrosandboxNameTooLongError extends Error {
+    readonly name = "MicrosandboxNameTooLongError";
+    readonly sandboxName: string;
+    readonly byteLength: number;
+    readonly maxByteLength = 128;
+    constructor(sandboxName: string, byteLength: number);
+}
+/**
+ * The create deadline supplied by the caller elapsed before the sandbox
+ * finished booting.
+ *
+ * The create itself is NOT abandoned: the SDK exposes no cancellation for it,
+ * so the adapter keeps watching that promise and, if the sandbox does finish
+ * booting afterwards, reclaims it (kill + remove) rather than leaving a
+ * running microVM nobody is waiting for and a name nobody can reuse.
+ */
+export declare class MicrosandboxCreateTimeoutError extends Error {
+    readonly name = "MicrosandboxCreateTimeoutError";
+    readonly sandboxName: string;
+    readonly timeoutMs: number;
+    constructor(sandboxName: string, timeoutMs: number);
+}
+/**
+ * A label lookup did not finish within its deadline.
+ *
+ * Raised rather than returning a partial page: a warm-lease decision made from
+ * a truncated listing is a decision made from data the caller cannot tell apart
+ * from "there is nothing else".
+ */
+export declare class MicrosandboxLookupTimeoutError extends Error {
+    readonly name = "MicrosandboxLookupTimeoutError";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, description: string);
+}
+/**
+ * A label listing could not be drained to a trustworthy end.
+ *
+ * Raised rather than returning what was collected so far. A short list and a
+ * complete one are indistinguishable to the caller, so a drain that gave up on
+ * a cursor that never advances, or on a page body it cannot read, would answer
+ * "there is nothing else" — and a warm-lease decision or a quota count made
+ * from that answer is made from data the provider never actually supplied.
+ */
+export declare class MicrosandboxPaginationError extends Error {
+    readonly name = "MicrosandboxPaginationError";
+    readonly pages: number;
+    constructor(pages: number, detail: string);
+}
+/**
+ * A call gave up waiting for the process-global backend gate.
+ *
+ * The gate exists because `withDefaultBackend` mutates ONE process-wide slot,
+ * so a call on backend A cannot run while backend B holds the scope. Normally
+ * the wait is short. It is NOT short when the scope holder has been abandoned:
+ * a create or a lookup that outlived its own client-side deadline returned a
+ * typed error to ITS caller, but the SDK exposes no cancellation, so the
+ * request is still in flight and the process-wide backend still has to be its
+ * own until it settles.
+ *
+ * Waiting forever in that situation deadlocks every other backend in the
+ * process. Running anyway would send this call to whatever backend the process
+ * default happens to hold, which is the one outcome the gate exists to prevent.
+ * So the queued call FAILS, loudly and with a typed error the caller can retry
+ * on — the honest third option.
+ */
+export declare class MicrosandboxBackendBusyError extends Error {
+    readonly name = "MicrosandboxBackendBusyError";
+    readonly waitedMs: number;
+    constructor(waitedMs: number);
+}
+/**
+ * `startScript` was called for a session id that is already admitted for a
+ * DIFFERENT command.
+ *
+ * Nothing was started and nothing was overwritten. A session id is the identity
+ * of one run's durable state; reusing it for another command would either
+ * strand the first run or report its exit code as the second one's.
+ */
+export declare class MicrosandboxSessionConflictError extends Error {
+    readonly name = "MicrosandboxSessionConflictError";
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * An admitted run can no longer produce an exit code.
+ *
+ * The wrapper writes the exit file as its final act, so a run whose process is
+ * gone without one — killed, out of memory, or interrupted by a sandbox
+ * restart — will never complete. Raised so a poll loop ends with a terminal
+ * outcome instead of asking forever.
+ */
+export declare class MicrosandboxRunLostError extends Error {
+    readonly name = "MicrosandboxRunLostError";
+    readonly sessionId: string;
+    readonly commandId: string;
+    readonly reason: string;
+    constructor(sessionId: string, commandId: string, reason: string);
+}
+/**
+ * `getExecLogs` was asked for a terminal result while the run is still going.
+ *
+ * The bootstrap-plane `ExecResult` has no "unfinished" value — its `exitCode`
+ * is a number — so returning one here would have to invent a code. Callers poll
+ * `getExecStatus` and read logs once it reports terminal.
+ */
+export declare class MicrosandboxRunNotFinishedError extends Error {
+    readonly name = "MicrosandboxRunNotFinishedError";
+    readonly sessionId: string;
+    readonly commandId: string;
+    constructor(sessionId: string, commandId: string);
+}
+/**
+ * The process-wide default backend could not be restored, so no later
+ * default-dependent SDK static may be issued from this process.
+ *
+ * `withDefaultBackend` sets one process-global slot and restores it on the way
+ * out. When the RESTORE is what failed, the slot holds an unknown value: not
+ * necessarily this runtime's backend, not necessarily the previous one. Every
+ * static the adapter calls reads that slot, so the only two honest options are
+ * to guess or to stop. This adapter stops — permanently, for the life of the
+ * process, because nothing it is willing to do can re-establish the truth.
+ * (Calling `setDefaultBackend` to force a known value would mutate the host
+ * process on behalf of a library, which this adapter never does.)
+ *
+ * Sandbox and handle instances resolved BEFORE the failure are unaffected and
+ * still usable: the SDK binds each one to the backend it was resolved on (its
+ * typings call this "backend retained by this sandbox"), so their exec,
+ * filesystem and lifecycle calls read no global state.
+ */
+export declare class MicrosandboxBackendPoisonedError extends Error {
+    readonly name = "MicrosandboxBackendPoisonedError";
+    constructor(cause: unknown);
+}
+/**
+ * A command finished, but the SDK reported no exit code for it.
+ *
+ * The bootstrap-plane `ExecResult.exitCode` is a number, so this adapter would
+ * have to INVENT one — and the only plausible invention, `0`, is the value that
+ * says "this succeeded". A command whose outcome the provider did not report is
+ * not a command that succeeded, so the caller is told the outcome is unknown
+ * instead of being told a comfortable lie it cannot detect.
+ */
+export declare class MicrosandboxUnknownOutcomeError extends Error {
+    readonly name = "MicrosandboxUnknownOutcomeError";
+    readonly sandboxName: string;
+    constructor(sandboxName: string);
+}
+/**
+ * The status probe for an async run did not produce a verdict.
+ *
+ * Distinct from {@link MicrosandboxRunLostError}, which IS a verdict — the run
+ * is over and cannot complete. This error says the adapter learned NOTHING:
+ * the guest call failed, a required guest-state read was unavailable, or it
+ * answered something this protocol does not define. Returning "still running"
+ * for any of those would be a positive claim the probe never made, and a poll
+ * loop reading it would wait for an outcome that may already have happened.
+ *
+ * It is safe to retry: nothing about the run was changed by asking.
+ */
+export declare class MicrosandboxStatusProbeError extends Error {
+    readonly name = "MicrosandboxStatusProbeError";
+    readonly sessionId: string;
+    readonly commandId: string;
+    /**
+     * `"transport"` — the probe call or a required guest-state read failed.
+     * `"unrecognized"` — it answered off-protocol.
+     */
+    readonly reason: "transport" | "unrecognized";
+    /** Retrying is harmless; the probe has no side effects on the run. */
+    readonly retryable = true;
+    constructor(sessionId: string, commandId: string, reason: "transport" | "unrecognized", detail: string, cause?: unknown);
+}
+/**
+ * A run's captured output could not be read.
+ *
+ * Raised instead of returning `""`. An empty log is a legitimate outcome — a
+ * command that printed nothing has one — so a failed read that answered `""`
+ * would be indistinguishable from a real result, and the caller would record
+ * "the command produced no output" as a fact about a read that never happened.
+ * A genuinely ABSENT log file still yields `""`, which is the one case where
+ * empty is the truth.
+ */
+export declare class MicrosandboxLogReadError extends Error {
+    readonly name = "MicrosandboxLogReadError";
+    readonly sessionId: string;
+    readonly path: string;
+    constructor(sessionId: string, path: string, detail: string, cause?: unknown);
+}
+/**
+ * `startScript`/`startExec` was given a `timeoutMs`, which this adapter cannot
+ * honour as the port defines it.
+ *
+ * The port's `timeoutMs` is the COMMAND's lifetime. For a synchronous
+ * `runScript` that is exactly what the SDK's `ExecOptionsBuilder.timeout` gives,
+ * so the sync path honours it. An async run is different: it is detached inside
+ * the guest by the durable wrapper and outlives the submit call, so the submit
+ * call's timeout bounds nothing about the command.
+ *
+ * The adapter previously applied it to the submit call anyway. That is the
+ * failure mode this error exists to remove — a caller that asked for a 30s
+ * command budget got a 30s SUBMIT budget and a command that runs forever, with
+ * nothing in the result to say so.
+ *
+ * It is refused rather than approximated because the honest enforcement is not
+ * available here: killing the run's shell on expiry would leave that shell's
+ * own descendants running, so the adapter would report a terminated run while
+ * the work continued — a fabricated outcome, which is worse than a refusal. Use
+ * `maxDurationSeconds` for a sandbox-lifetime bound, or put the bound in the
+ * command itself (`timeout 30 ...`), where the guest can enforce it properly.
+ */
+export declare class MicrosandboxRunTimeoutUnsupportedError extends Error {
+    readonly name = "MicrosandboxRunTimeoutUnsupportedError";
+    readonly sessionId: string;
+    readonly timeoutMs: number;
+    constructor(sessionId: string, timeoutMs: number);
+}
+/**
+ * Reset the module-global gate. TEST-ONLY.
+ *
+ * The gate is process-global on purpose, and poisoning it is permanent on
+ * purpose — which makes the poison path untestable in-process without a way
+ * back. Exported from the module but NOT from the package barrel, so it is
+ * reachable from this file's tests and from nowhere a consumer imports.
+ *
+ * @internal
+ */
+export declare function __resetBackendGateForTests(): void;
+/**
+ * How many callers are queued on the gate right now. TEST-ONLY.
+ *
+ * The leak this exists to catch is INVISIBLE from the outside: a waiter that
+ * timed out still reports the same typed `MicrosandboxBackendBusyError` to its
+ * caller whether or not it deregistered itself, so a test written against
+ * observable behaviour alone passes against the bug. The only discriminating
+ * signal is the length of the queue itself, so the queue is what the test
+ * asserts on.
+ *
+ * @internal
+ */
+export declare function __backendGateWaiterCountForTests(): number;
+export declare class MicrosandboxRuntime implements SandboxRuntime, WorkflowRuntime {
+    readonly id = "microsandbox";
+    /**
+     * Bootstrap-plane capabilities. These describe what THIS ADAPTER exposes
+     * through the port, not everything the SDK can do — the same convention the
+     * Daytona adapter follows.
+     *
+     * TWO OF THESE ARE BACKEND-SENSITIVE, and both were previously reported as
+     * flat process-wide constants — which published a claim about the cloud
+     * backend that this package cannot stand behind. They are now derived from
+     * the backend this instance is bound to.
+     *
+     *  - `pty: false` — the SDK's `ExecOptionsBuilder.tty(true)` and
+     *    `ExecHandle.resize()` are real, but the port has no pty method and this
+     *    adapter never allocates one.
+     *  - `snapshots` — LOCAL only, and the claim is about THIS ADAPTER's boot
+     *    path, not about the provider's hosted service. `launch` sources a
+     *    sandbox through the builder's `fromSnapshot`, which consumes a
+     *    host-local artifact: the installed SDK's typings describe `Snapshot` as
+     *    "an artifact on disk" and resolve one under
+     *    `~/.microsandbox/snapshots/<name>/`. This adapter never transfers that
+     *    artifact anywhere, so on a remote backend there is nothing for a create
+     *    to resolve — hence `false`, and a constructor that refuses the pairing.
+     *    Note the adapter only ever CONSUMES a snapshot; it never creates one, so
+     *    `SandboxHandle.snapshot()` is not on this path.
+     *  - `isolation` — `'strong'` on LOCAL, `'unknown'` on CLOUD, and both values
+     *    describe what this package has ESTABLISHED rather than what any provider
+     *    documentation says. Locally the SDK boots each sandbox as a microVM with
+     *    its own guest kernel on a virtualization-capable host, and the installed
+     *    package states that requirement itself (Node 22+, a native addon, KVM /
+     *    Apple Silicon / WHP), so `'strong'` rests on something checkable here.
+     *    For the cloud backend this adapter observes nothing about isolation,
+     *    region placement or resource enforcement and measures nothing against
+     *    them, so it reports `'unknown'` — which is a statement about this
+     *    package's evidence, not an assertion that the guarantee is absent. See
+     *    {@link IsolationLevel}.
+     *  - `persistentHandle: true` — a sandbox is re-resolvable by name from a
+     *    fresh process via `Sandbox.get(name)` + `connect()`, and
+     *    `launchDetached` sets `detached(true)` so it outlives this process.
+     *  - `streamingLogs: false` — the SDK ships `logStream({follow:true})` and
+     *    `execStream`, but this adapter's log path is a durable file read, so
+     *    claiming a streaming capability here would be claiming a code path that
+     *    does not exist.
+     *
+     * NOT SUPPORTED, and deliberately absent rather than silently ignored: custom
+     * or published PORTS. The SDK builder exposes `port()`/`portBind()`/`portUdp()`,
+     * but the ports this package targets have no public-port surface to express
+     * them, so this adapter never calls them and never implies a reachable port.
+     */
+    readonly capabilities: RuntimeCapabilities;
+    /**
+     * Both true, and declared rather than left to default so the reasoning is on
+     * the record. `warmLease`: `Sandbox.listWith(b => b.labels(...))` is a real
+     * server-side label query with cursor pagination, so a warm-lease lookup is
+     * meaningful. `lifecycle`: `start`/`stop` map onto `SandboxHandle.start()` /
+     * `SandboxHandle.stop()`, which genuinely resume and halt a microVM — unlike
+     * the E2B adapter, where both are no-ops. Both apply to sandboxes this
+     * runtime OWNS; an attached sandbox is deliberately left alone.
+     */
+    readonly declaredCapabilities: {
+        readonly warmLease: true;
+        readonly lifecycle: true;
+    };
+    private readonly backend;
+    private readonly image?;
+    private readonly snapshot?;
+    private readonly homeDir;
+    private readonly defaultWorkdir?;
+    private readonly cpus?;
+    private readonly memoryMiB?;
+    private readonly idleTimeoutSeconds?;
+    private readonly maxDurationSeconds?;
+    private readonly replaceExisting;
+    private readonly namePrefix;
+    private readonly runStateDir;
+    private readonly shell;
+    private readonly connectTimeoutMs;
+    private readonly lookupTimeoutMs;
+    private readonly listPageSize;
+    private readonly backendQueueTimeoutMs;
+    private readonly injectedSdk?;
+    private readonly onReclaimFailure?;
+    private sdkPromise?;
+    private readonly registry;
+    private readonly pendingReclaims;
+    constructor(options: MicrosandboxRuntimeOptions);
+    findByLabels(labels: Record<string, string>, options?: SandboxLookupOptions): Promise<RuntimeHandle | null>;
+    findAllByLabels(labels: Record<string, string>, options?: SandboxLookupOptions): Promise<RuntimeHandle[]>;
+    countByLabels(labels: Record<string, string>, options?: SandboxCountOptions): Promise<number>;
+    /**
+     * Drain the cursor-paginated, server-side label listing, keeping the entries
+     * that match `states` and are not excluded, and stopping as soon as `cap`
+     * such handles are collected or the lookup deadline elapses.
+     */
+    private collectByLabels;
+    getById(id: string, options?: {
+        states?: readonly string[] | null;
+        owned?: boolean;
+        homeDir?: string;
+        workdir?: string;
+    }): Promise<RuntimeHandle | null>;
+    launch(options?: LaunchOptions): Promise<RuntimeHandle>;
+    launchDetached(options?: LaunchOptions): Promise<RuntimeHandle>;
+    private createSandbox;
+    /**
+     * Take responsibility for a create that lost the race with its deadline.
+     *
+     * The SDK offers no way to cancel an in-flight create, so the promise is
+     * watched instead of dropped. Two things follow from that, and both matter:
+     * the eventual rejection is consumed here (an abandoned rejected promise is
+     * an unhandled rejection, which crashes a Node process configured to treat
+     * them as fatal), and an eventual SUCCESS is reclaimed — the caller already
+     * saw a failure, so a sandbox nobody is waiting for would otherwise burn
+     * provider resources and hold its name against the next launch.
+     */
+    private reclaimLateCreate;
+    private resolveName;
+    /**
+     * Bootstrap-plane exec. Same call as `runScript`, narrower result shape.
+     *
+     * `ExecResult.exitCode` is a `number`, and `RunScriptResult.exitCode` is
+     * `number | null`, so this is where a missing outcome would have to be
+     * invented. It is not: a `null` becomes a typed error rather than the `0`
+     * that would report an unobserved command as a successful one.
+     */
+    exec(handle: RuntimeHandle, command: string, options?: ExecOptions): Promise<ExecResult>;
+    runScript(handle: RuntimeHandle, options: {
+        command: string;
+        sessionId?: string;
+        cwd?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+    }): Promise<RunScriptResult>;
+    /**
+     * Submit one durable async run.
+     *
+     * The guest wrapper (see {@link MICROSANDBOX_RUN_ADMIT_SCRIPT}) claims the
+     * session's run directory with an atomic `mkdir`, so this is idempotent in
+     * the way that actually matters for an outcome-unknown submit: a retry of
+     * the SAME command adopts the run that is already there (`reconciled: true`)
+     * instead of starting a second one, and a retry with a DIFFERENT command is
+     * refused instead of overwriting the first run's state.
+     */
+    startScript(handle: RuntimeHandle, options: {
+        command: string;
+        sessionId?: string;
+        cwd?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+        suppressInputEcho?: boolean;
+    }): Promise<AsyncRunStartResult>;
+    getScriptStatus(handle: RuntimeHandle, sessionId: string, commandId: string): Promise<AsyncRunStatus>;
+    getScriptLogs(handle: RuntimeHandle, sessionId: string, commandId: string): Promise<RunScriptResult>;
+    startExec(handle: RuntimeHandle, command: string, options?: ExecOptions & {
+        sessionId?: string;
+    }): Promise<AsyncExecStartResult>;
+    getExecStatus(handle: RuntimeHandle, sessionId: string, commandId: string): Promise<AsyncExecStatus>;
+    /**
+     * Terminal result of an async run: its captured output AND the exit code the
+     * run actually recorded.
+     *
+     * The exit code comes from `getScriptStatus`, never from the log read.
+     * `getScriptLogs` reports `exitCode: null` by design, and defaulting that to
+     * `0` here would report every unfinished — and every lost — run as a success.
+     */
+    getExecLogs(handle: RuntimeHandle, sessionId: string, commandId: string): Promise<ExecResult>;
+    /**
+     * Put one file into the guest.
+     *
+     * A `string` source is a HOST PATH and a `Buffer` source is file CONTENT —
+     * the same split the Daytona adapter uses, so this class's `uploadFile` and
+     * `uploadBundle` cannot disagree with each other.
+     */
+    uploadFile(handle: RuntimeHandle, source: string | Buffer, destination: string): Promise<void>;
+    uploadBundle(handle: RuntimeHandle, options: {
+        files: Array<{
+            source: string | Buffer;
+            destination: string;
+        }>;
+    }): Promise<void>;
+    downloadFile(handle: RuntimeHandle, source: string, destination?: string): Promise<Buffer | void>;
+    getHomeDir(handle: RuntimeHandle): Promise<string>;
+    start(handle: RuntimeHandle): Promise<RuntimeHandle>;
+    stop(handle: RuntimeHandle): Promise<void>;
+    /**
+     * Halt the sandbox AND drop its database record — but only if this runtime
+     * owns it.
+     *
+     * Both halves of the teardown matter: the name is the identity, so leaving a
+     * stopped record behind would make the next `launch` under that name collide.
+     * The ownership check matters more: `destroy` is the one call here that
+     * cannot be undone, and a lease-reattach path that resolved a borrowed
+     * sandbox by name must not be able to delete it. An unowned (or unknown)
+     * handle drops this runtime's local state and makes no remote call at all.
+     */
+    destroy(handle: RuntimeHandle): Promise<void>;
+    /**
+     * Stop-if-running + remove by name, with no ownership check.
+     *
+     * Private on purpose: the only callers are `destroy` (which has already
+     * checked) and the reclamation of a create that landed after its deadline
+     * (which is reclaiming a sandbox this runtime itself asked for).
+     *
+     * Backend-safe order — this is what makes the destroy path work on the
+     * hosted cloud backend. `SandboxHandle.kill()` is not implemented there:
+     * the SDK answers it with `UnsupportedError` (code `"unsupported"`,
+     * message `"Sandbox::kill is not supported by this backend: use
+     * Sandbox::stop"`), and the previous code re-threw that error before
+     * `remove()` was ever reached, so every cloud destroy left a running
+     * sandbox behind. `stop()` works on both backends, so the sequence is:
+     *
+     *   1. Try `kill()` — a stronger, faster teardown that local supports.
+     *   2. If the backend answers `Unsupported`, fall back to `stop()` — the
+     *      call the hosted backend documents.
+     *   3. Either way, `remove()` clears the record (which requires the
+     *      sandbox to be stopped, and cannot delete a still-running one).
+     *
+     * `already-stopped` and `not-found` on the first-step call are both fine
+     * because they mean the same thing for the caller: the sandbox is
+     * quiescent by the time `remove()` runs. Any other error is fatal to the
+     * teardown and re-thrown, so the caller retains responsibility.
+     */
+    private forceDestroy;
+    private sdk;
+    /**
+     * Run one DEFAULT-DEPENDENT SDK static with this runtime's backend in scope.
+     *
+     * `setDefaultBackend` is never called from this adapter: constructing a
+     * runtime must not mutate the host process. The scoped form IS process-wide
+     * while it is open, which is why every static goes through the module's
+     * backend gate (see `withBackendScope`) rather than opening its own scope.
+     *
+     * ONLY the three statics this adapter calls belong here — `Sandbox.builder`
+     * (through its terminal `create()`), `Sandbox.get` and `Sandbox.listWith`.
+     * Operations on a resolved `Sandbox` or `SandboxHandle` are bound to the
+     * backend they were resolved on and are issued directly, off the gate.
+     */
+    private withBackendStatic;
+    private lookupHandle;
+    private register;
+    private isOwned;
+    /** Drop the live connection but keep what this runtime knows about the name. */
+    private forgetInstance;
+    private requireSandbox;
+    private ensureParentDir;
+    /**
+     * Read one run's captured output, bounded, without turning a failure into an
+     * empty log.
+     *
+     * The read goes through {@link MICROSANDBOX_RUN_LOG_SCRIPT} rather than
+     * `fs.readToString` for two reasons that both matter to the caller: an
+     * ABSENT log is a success with no output (a run that has printed nothing has
+     * one), and everything else — an unreadable file, a failed guest call — is a
+     * failure. The previous form could not tell those apart, because it answered
+     * `""` to all of them.
+     *
+     * One byte MORE than the cap is requested, so a longer log is detectable
+     * rather than silently tailed: the extra byte is what turns "here is the
+     * output" into "here is the last `maxBytes` of it".
+     */
+    private readRunLog;
+    private lookupDeadline;
+    /**
+     * Run `build` under the ONE overall deadline, cancelling its admission when
+     * that deadline expires.
+     *
+     * Racing a timer against the operation is not enough on its own. The gate is
+     * a queue, so a lookup that gives up while queued is still queued: it can be
+     * admitted later and issue a static against the process default long after
+     * the caller stopped waiting for it. The signal is what actually withdraws
+     * it from the queue.
+     */
+    private awaitWithinCancelling;
+    private awaitWithin;
+    /**
+     * Guest directory holding one session's run state.
+     *
+     * The encoding is reversible, so two different session ids can never land on
+     * one directory. A sanitizing replacement cannot promise that: it maps `a/b`
+     * and `a_b` onto the same path, which is enough to hand one run's exit code
+     * to the other.
+     */
+    private scriptRunDir;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map