@prized/sdk 0.0.0-stage → 0.1.1

package/dist/esm/files.js

@@ -0,0 +1,381 @@
+// sandbox.files: read, write, list, remove, upload, download.
+import { PrizedError } from './errors.js';
+import { request } from './http.js';
+import { mayHaveActed, removeEffect, withOutcome, writeEffect } from './outcome.js';
+import { existsScript, listScript, removeScript, sandboxPath, shellQuote, WORKSPACE_DIR } from './shell.js';
+import { helperExec, MAX_FILE_BYTES, rawExec } from './toolbox.js';
+/**
+ * The sandbox's file transfers take at most this long, retries included:
+ * the edge's own limit on one transfer. A write's upload sent again (a
+ * staged one is, after a lost answer or a 502, 503 or 504) is sent only
+ * while time is left, so a transfer that timed out is not.
+ */
+export const FILE_TIMEOUT_MS = 10 * 60_000;
+function byteSize(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data).length;
+    if (data instanceof Uint8Array)
+        return data.byteLength;
+    if (data instanceof ArrayBuffer)
+        return data.byteLength;
+    return data.size;
+}
+async function nodeFs() {
+    try {
+        return (await import('node:fs/promises'));
+    }
+    catch (cause) {
+        throw new PrizedError('invalid_argument', 'upload() and download() need a local file system (Node, Bun or Deno); use write() and readBytes() instead.', { cause });
+    }
+}
+// A write goes up under a fresh name beside its target, and one command then
+// renames it over the target, giving it the replaced file's permission bits
+// first: uploaded straight over a file, the bytes would land 0600 on some
+// sandbox images, and a 0755 script would stop running (exit 126). A new file
+// keeps the mode the files API gave the staged one, its own rule for new
+// files, so a write follows the same rules on every image. The Python SDK
+// renders the same script (_core.py publish_command; sdk/file-scripts).
+const HOME_DIR = '/home/prized';
+/** A staged write's name, beside its target. */
+const STAGING_PREFIX = '.prized-write-';
+/** The publish script's own exits (the Python SDK's too). */
+export const EXIT_TARGET_IS_LINK = 47;
+export const EXIT_TARGET_NOT_REGULAR = 48;
+/** How long removing a staged file that was never put in place may take. */
+const DISCARD_MS = 10_000;
+/** A write's own commands: a rename, a chmod or an rm. */
+const WRITE_COMMAND_MS = 60_000;
+/**
+ * For the staged upload: the target is changed only by the command that
+ * follows it. The upload may have been sent again, so it says only what to
+ * do (langchain-prized's staged_upload_effect words it the same).
+ */
+function stagedEffect(path) {
+    return {
+        maybe: `${path} was not changed (its new bytes may have reached the sandbox, but were not put in place)`,
+        did: `${path} was not changed yet`,
+        check: 'Write it again.',
+    };
+}
+/** For the command that puts the staged upload in place: a 2xx proves it ran, not how it ended. */
+function publishEffect(path) {
+    return { ...writeEffect(path), did: `${path} may or may not have been written: the command that puts it in place ran` };
+}
+function randomHex(bytes) {
+    const out = new Uint8Array(bytes);
+    const webcrypto = globalThis.crypto;
+    if (webcrypto?.getRandomValues) {
+        webcrypto.getRandomValues(out);
+    }
+    else {
+        for (let i = 0; i < bytes; i += 1)
+            out[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(out, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Where a write to `target` is staged: `clean` is the target as the files
+ * API reads it (`.`, `//` and a trailing `/` gone), and `staging` a fresh
+ * name in the same directory. Null when the files API has to judge the path
+ * itself (outside /home/prized, `..`, NUL): it is then uploaded as it is, and
+ * refused as it always was.
+ */
+export function stagingFor(target, suffix = randomHex(16)) {
+    if (!target.startsWith('/') || target.includes('\0'))
+        return null;
+    const parts = target.split('/').filter((part) => part !== '' && part !== '.');
+    if (parts.includes('..'))
+        return null;
+    const clean = `/${parts.join('/')}`;
+    if (!clean.startsWith(`${HOME_DIR}/`))
+        return null;
+    return { clean, staging: `${clean.slice(0, clean.lastIndexOf('/') + 1)}${STAGING_PREFIX}${suffix}` };
+}
+/**
+ * The command that puts the staged upload `staging` in place at `target`
+ * (both absolute, in one directory) with one rename. A regular file there
+ * lends its permission bits (setuid, setgid and sticky are not carried) and,
+ * where the sandbox user may, its owner and group; `mode`, when given, sets
+ * the bits instead. With nothing there the staged file keeps the files API's
+ * mode for a new file. A link there exits 47 and a directory or other
+ * non-regular file exits 48, changing nothing. The command removes the
+ * staged file as it exits (unless it is killed).
+ */
+export function publishScript(staging, target, mode) {
+    const chmod = (bits) => `chmod ${bits} -- "$src" || exit`;
+    return [
+        `src=${shellQuote(staging)}`,
+        `dst=${shellQuote(target)}`,
+        `trap 'rm -f -- "$src"' EXIT`,
+        // One lstat: the type, the bits and the owner come from the same file.
+        // `+`: the ids as numbers, never looked up as names.
+        `if s=$(stat -c '%f +%u:+%g' -- "$dst" 2> /dev/null); then`,
+        `  t=$((0x\${s%% *} & 0170000))`,
+        `  [ "$t" -eq $((0120000)) ] && exit ${EXIT_TARGET_IS_LINK}`,
+        `  [ "$t" -eq $((0100000)) ] || exit ${EXIT_TARGET_NOT_REGULAR}`,
+        `  chown -- "\${s#* }" "$src" 2> /dev/null || chgrp -- "\${s##*:}" "$src" 2> /dev/null`,
+        ...(mode === null ? [`  ${chmod('"$(printf %o $((0x${s%% *} & 0777)))"')}`, 'fi'] : ['fi', chmod(mode.toString(8))]),
+        `mv -fT -- "$src" "$dst" || exit`,
+        // The rename is on disk before the answer, as an upload's is.
+        `sync -- "\${dst%/*}" 2> /dev/null`,
+        'exit 0',
+    ].join('\n');
+}
+/** A command's stderr in one line, for an error message. */
+function commandDetail(result) {
+    return result.stderr.trim().replace(/\s+/g, ' ').slice(0, 300) || `exit ${result.exitCode}`;
+}
+/** An upload or command answered 2xx whose body could not be read: it took effect. */
+function landed(error) {
+    return error instanceof PrizedError && error.status !== null && error.status >= 200 && error.status < 300;
+}
+function checkMode(mode, sandboxId) {
+    if (mode === undefined)
+        return null;
+    if (typeof mode !== 'number' || !Number.isInteger(mode) || mode < 0 || mode > 0o777) {
+        throw new PrizedError('invalid_argument', `mode must be permission bits from 0 to 0o777 (0o755 for a script), got ${String(mode)}.`, { sandboxId });
+    }
+    return mode;
+}
+function parentDir(path) {
+    const cut = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return cut > 0 ? path.slice(0, cut) : null;
+}
+/** File operations on one sandbox. Paths are absolute, or relative to /home/prized/work. */
+export class Files {
+    toolbox;
+    /** @internal */
+    constructor(toolbox) {
+        this.toolbox = toolbox;
+    }
+    url(op, path) {
+        return `${this.toolbox.base()}/files/${op}?path=${encodeURIComponent(sandboxPath(path))}`;
+    }
+    /** A file's contents as UTF-8 text. */
+    async read(path) {
+        return new TextDecoder('utf-8').decode(await this.readBytes(path));
+    }
+    /** A file's contents as bytes (at most 100 MiB). */
+    async readBytes(path) {
+        const result = await request(this.toolbox.config, {
+            method: 'GET',
+            url: this.url('download', path),
+            retry: 'safe',
+            read: 'bytes',
+            timeoutMs: FILE_TIMEOUT_MS,
+            deadline: this.toolbox.config.now() + FILE_TIMEOUT_MS,
+            sandboxId: this.toolbox.sandboxId,
+        });
+        return result.bytes ?? new Uint8Array(0);
+    }
+    /**
+     * Write a file (at most 100 MiB), replacing it whole if it exists. Missing
+     * parent directories are created. The path must be inside /home/prized.
+     * A file that is replaced keeps its mode, so a script made executable
+     * stays executable; a new file gets the sandbox's default (0600 in
+     * prized-base-v1 and prized-agent-v1). `mode` sets the permission bits either way.
+     * The bytes go up under a temporary name beside the file, sent again if
+     * need be (a lost answer, a 502, 503 or 504; all copies within the
+     * transfer's 10 minutes),
+     * and one command that is never sent again puts them in place: a write
+     * whose answer to that command was lost throws, since it may have landed
+     * and the sandbox written the file since (read it back, or write again,
+     * as suits the file).
+     */
+    async write(path, data, options = {}) {
+        const sandboxId = this.toolbox.sandboxId;
+        const size = byteSize(data);
+        if (size > MAX_FILE_BYTES) {
+            throw new PrizedError('file_too_large', null, { sandboxId });
+        }
+        const mode = checkMode(options.mode, sandboxId);
+        const target = sandboxPath(path);
+        const plan = stagingFor(target);
+        if (plan === null)
+            return this.send(target, data, size, target, writeEffect(target), 'exec');
+        const { clean, staging } = plan;
+        try {
+            // Every copy to the same fresh name, which only the command below puts in place.
+            await this.send(staging, data, size, clean, stagedEffect(clean), 'staged');
+        }
+        catch (error) {
+            // A 2xx whose body could not be read: the staged bytes are all there.
+            if (!landed(error)) {
+                // Removed only if a copy may have landed: a refusal, or copies that
+                // never arrived, left nothing, and a command would wake a sandbox
+                // the edge's refusal left paused.
+                if (mayHaveActed(error))
+                    await this.discard(staging);
+                throw error;
+            }
+        }
+        let result;
+        try {
+            // Like any write: a lost answer is not sent again (it may have renamed).
+            result = await this.run(publishScript(staging, clean, mode), { retry: 'exec', effect: publishEffect(clean) });
+        }
+        catch (error) {
+            // Unless it ran (a 2xx), the staged file may still be there; once it
+            // ran, the command removed it itself.
+            if (!landed(error))
+                await this.discard(staging);
+            throw error;
+        }
+        if (result.timedOut) {
+            await this.discard(staging); // killed, perhaps before it could remove it
+            throw withOutcome(new PrizedError('command_timeout', `Putting ${clean} in place timed out.`, { sandboxId }), writeEffect(clean), 'maybe');
+        }
+        if (result.exitCode === 0)
+            return { path: clean, size };
+        if (result.exitCode === EXIT_TARGET_IS_LINK) {
+            // A link: the files API follows it or refuses it, as for any upload.
+            const info = await this.send(clean, data, size, clean, writeEffect(clean), 'exec');
+            if (mode !== null)
+                await this.chmod(clean, mode);
+            return info;
+        }
+        if (result.exitCode === EXIT_TARGET_NOT_REGULAR) {
+            throw new PrizedError('unsupported_file_type', `${clean} is a directory or another file that is not a regular file; only a regular file can be written.`, { sandboxId });
+        }
+        const denied = /Permission denied|Operation not permitted/.test(result.stderr);
+        throw new PrizedError(denied ? 'permission_denied' : 'command_failed', `Could not write ${clean}: ${commandDetail(result)}`, { sandboxId });
+    }
+    /**
+     * One upload to `path`, as the files API takes it; `target` is the file the
+     * caller asked for, and `effect` what the upload does to it. `exec` for an
+     * upload straight to the file: like a command, a resend after the answer
+     * was lost could overwrite what the sandbox wrote to the path since.
+     * `staged` for one to a fresh name: sent again like a read.
+     */
+    async send(path, data, size, target, effect, retry) {
+        const result = await request(this.toolbox.config, {
+            method: 'POST',
+            url: this.url('upload', path),
+            body: data,
+            contentType: 'application/octet-stream',
+            retry,
+            effect,
+            timeoutMs: FILE_TIMEOUT_MS,
+            deadline: this.toolbox.config.now() + FILE_TIMEOUT_MS,
+            sandboxId: this.toolbox.sandboxId,
+        });
+        const doc = (result.json ?? {});
+        return {
+            path: path === target && typeof doc.path === 'string' ? doc.path : target,
+            size: typeof doc.size === 'number' ? doc.size : size,
+        };
+    }
+    /**
+     * Remove a staged upload that was not put in place (best effort: the
+     * write's own error matters more). Sent again like a read, unlike other
+     * removes: the name is this call's own, so a second rm finds nothing
+     * anyone else made.
+     */
+    async discard(staging) {
+        try {
+            await this.run(removeScript(staging, false), { retry: 'safe', deadline: this.toolbox.config.now() + DISCARD_MS });
+        }
+        catch {
+            // The write's error is the one to report.
+        }
+    }
+    async chmod(path, mode) {
+        const result = await this.run(`chmod ${mode.toString(8)} -- ${shellQuote(path)}`, { retry: 'safe' });
+        if (result.exitCode !== 0) {
+            throw new PrizedError('command_failed', `${path} was written, but its mode could not be set: ${commandDetail(result)}`, {
+                sandboxId: this.toolbox.sandboxId,
+            });
+        }
+    }
+    /** One of a write's own commands, run in the home, which is always there (the workspace may not be). */
+    run(script, options) {
+        return rawExec(this.toolbox, { command: script, cwd: HOME_DIR, timeoutMs: WRITE_COMMAND_MS }, options);
+    }
+    /** A directory's entries, sorted by name (default: /home/prized/work). */
+    async list(path = WORKSPACE_DIR) {
+        const dir = sandboxPath(path).replace(/(.)\/+$/, '$1');
+        const result = await helperExec(this.toolbox, listScript(dir));
+        if (result.exitCode === 20) {
+            throw new PrizedError('not_directory', `${dir} is not a directory.`, { sandboxId: this.toolbox.sandboxId });
+        }
+        if (result.exitCode === 21) {
+            throw new PrizedError('not_found', `${dir} does not exist.`, { sandboxId: this.toolbox.sandboxId });
+        }
+        if (result.exitCode !== 0) {
+            throw new PrizedError('command_failed', result.stderr.trim() || `list exited ${result.exitCode}`, {
+                sandboxId: this.toolbox.sandboxId,
+            });
+        }
+        if (result.truncated) {
+            // Past the per-call output cap the listing is incomplete: say so rather
+            // than return a short array that looks whole.
+            throw new PrizedError('command_failed', `${dir} has too many entries to list in one call; list a narrower directory.`, {
+                sandboxId: this.toolbox.sandboxId,
+            });
+        }
+        const entries = [];
+        for (const rec of result.stdout.split('\0')) {
+            if (rec === '')
+                continue;
+            const parts = rec.split('\t');
+            if (parts.length < 5)
+                continue;
+            const [type, size, mode, mtime] = parts;
+            const name = parts.slice(4).join('\t');
+            const seconds = Number(mtime);
+            entries.push({
+                name,
+                path: dir === '/' ? `/${name}` : `${dir}/${name}`,
+                size: Number(size) || 0,
+                isDir: type === 'd',
+                isSymlink: type === 'l',
+                mode,
+                modified: Number.isFinite(seconds) ? new Date(Math.round(seconds * 1000)) : null,
+            });
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        return entries;
+    }
+    /** Whether a path exists (a file, a directory, or a link, even a dangling one). */
+    async exists(path) {
+        const result = await helperExec(this.toolbox, existsScript(sandboxPath(path)));
+        if (result.exitCode === 0)
+            return true;
+        if (result.exitCode === 1)
+            return false;
+        throw new PrizedError('command_failed', result.stderr.trim() || `exists exited ${result.exitCode}`, {
+            sandboxId: this.toolbox.sandboxId,
+        });
+    }
+    /** Remove a file, or a directory tree with `recursive: true`. A missing path is not an error. */
+    async remove(path, options = {}) {
+        const target = sandboxPath(path);
+        // Command retry rules: a lost answer is not sent again, or a path the
+        // sandbox recreated in the meantime would be deleted too.
+        const result = await helperExec(this.toolbox, removeScript(target, options.recursive === true), {
+            retry: 'exec',
+            effect: removeEffect(target),
+        });
+        if (result.exitCode !== 0) {
+            throw new PrizedError('command_failed', result.stderr.trim() || `rm exited ${result.exitCode}`, {
+                sandboxId: this.toolbox.sandboxId,
+            });
+        }
+    }
+    /** Copy a local file into the sandbox (Node, Bun, Deno), as write() does. */
+    async upload(localPath, remotePath, options = {}) {
+        const fs = await nodeFs();
+        const data = await fs.readFile(localPath);
+        return this.write(remotePath, new Uint8Array(data.buffer, data.byteOffset, data.byteLength), options);
+    }
+    /** Copy a file out of the sandbox to a local path (Node, Bun, Deno). Returns the byte count. */
+    async download(remotePath, localPath) {
+        const fs = await nodeFs();
+        const bytes = await this.readBytes(remotePath);
+        const parent = parentDir(localPath);
+        if (parent !== null)
+            await fs.mkdir(parent, { recursive: true });
+        await fs.writeFile(localPath, bytes);
+        return bytes.byteLength;
+    }
+}

package/dist/esm/http.d.ts

@@ -0,0 +1,226 @@
+import { PrizedError } from './errors.js';
+import { type Effect, type Outcome } from './outcome.js';
+export declare const DEFAULT_BASE_URL = "https://api.prized.dev";
+export declare const DEFAULT_EDGE_URL = "https://term.prized.dev";
+/** Options every entry point accepts. All optional. */
+export interface ClientOptions {
+    /** Your API key (`dcp_…`). Default: the `PRIZED_API_KEY` environment variable. */
+    apiKey?: string;
+    /**
+     * The API origin: https, or plain http only on this machine (`localhost`,
+     * `127.0.0.1`, `[::1]`). Default: `https://api.prized.dev`.
+     */
+    baseUrl?: string;
+    /**
+     * The origin that serves exec and files, by the same rule as `baseUrl`.
+     * Default: the `toolboxBase` the API returns for each sandbox (today
+     * `https://term.prized.dev`), on a host trusted beside the API's
+     * (toolboxBaseFor).
+     */
+    edgeUrl?: string;
+    /** A fetch implementation. Default: the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Retries after the first attempt for retryable failures. Default 3. */
+    maxRetries?: number;
+    /** Per-request timeout for API calls, in ms. Default 60 000. */
+    requestTimeoutMs?: number;
+    /** The longest the SDK's own polling goes between checks, in ms (the first come sooner); excludes
+     *  the request itself and the API's hold of a create, pause or resume. Default 500. */
+    pollIntervalMs?: number;
+    /**
+     * How long a wait keeps polling while its polls fail (no answer, a 5xx, a
+     * rate limit), in ms, before it gives up: a streamed or long `exec` then
+     * stops the command, a handle's `wait()` throws. Default 120 000. `0`
+     * gives up once one poll's retries run out. `exec` and `wait()` take it
+     * per call too.
+     */
+    pollOutageMs?: number;
+    /** Sleep seam (tests inject one that never really waits). */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Clock seam: epoch milliseconds. Default `Date.now`. */
+    now?: () => number;
+    /** Jitter seam: a number in [0, 1). Default `Math.random`. */
+    random?: () => number;
+}
+export interface Config {
+    apiKey: string;
+    baseUrl: string;
+    edgeUrl: string | null;
+    fetch: typeof fetch;
+    maxRetries: number;
+    requestTimeoutMs: number;
+    pollIntervalMs: number;
+    pollOutageMs: number;
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now: () => number;
+    random: () => number;
+}
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * How long a wait (a streamed or long exec, a handle's wait()) keeps polling
+ * while its polls fail before it gives up (pollOutageMs), and a streamed or
+ * long exec stops its command: long enough to ride out a dropped connection
+ * or an edge that restarts. The Python SDK's DEFAULT_POLL_OUTAGE.
+ */
+export declare const DEFAULT_POLL_OUTAGE_MS = 120000;
+/** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
+export declare function validOutage(value: number | undefined): number | undefined;
+export declare function resolveConfig(options?: ClientOptions): Config;
+/**
+ * Where exec and files go for one sandbox. An explicit edgeUrl wins; else the
+ * API's own `toolboxBase` when it has the expected shape (https, or plain
+ * http on loopback for local development, ending /v1/sandbox/<id>) on a host
+ * trusted beside the API's (term.prized.dev beside api.prized.dev; see
+ * trustedEdge); else the default edge, for Prized's own API only. The API key
+ * is never sent anywhere else: discovery is routing, not authority.
+ */
+export declare function toolboxBaseFor(config: Config, sandboxId: string, toolboxBase: string | null): string;
+/**
+ * The edge this config's sandboxes answer on, before the API has named one:
+ * an explicit edgeUrl, else the default edge for the default API. null for
+ * any other API, whose edge is known only from its answer.
+ */
+export declare function expectedEdge(config: Config): string | null;
+/**
+ * Open a connection to the edge before the first command needs it: one
+ * `GET /healthz` without the API key (the route needs none), its body read
+ * so the connection goes back to the pool. Sent beside a held create, it
+ * takes DNS, TCP and TLS off the first command after the sandbox runs. Best
+ * effort: never throws, and an edge it cannot reach costs only itself.
+ */
+export declare function warmEdge(config: Config): Promise<void>;
+/**
+ * Which failures a request may retry (sdk/retry-spec.json, which the
+ * Python SDK shares, lists which calls take which):
+ * - `safe`: the request can be repeated without a second effect (reads,
+ *   state verbs, creates and forks that carry an Idempotency-Key).
+ *   Retries network failures, 429/502/503/504, and everything `exec`
+ *   retries (the edge's 500 control_plane_unavailable among them). A GET
+ *   retries any 500 too (the API's `internal`).
+ * - `exec`: a command, an upload or a remove: what the sandbox does
+ *   meanwhile could be undone by a second copy. Retried only when it
+ *   provably never arrived: a connection that never opened, or an answer
+ *   saying so (the edge's rate limit, its lookup failing). A lost answer
+ *   is never retried: it may already have run.
+ * - `staged`: a write's upload to a fresh name beside its target, which only
+ *   a command after it puts in place (files.ts). Retried as `safe` (a lost
+ *   answer, a timeout, 429/502/503/504) and `exec` both, a GET's 500 aside:
+ *   every copy writes the same bytes under the same name, which nothing else
+ *   writes, so a second one changes no file of the caller's. A 2xx whose body
+ *   broke off is not sent again: the bytes are there. Its error says whether
+ *   a copy may have reached the sandbox.
+ */
+export type RetryMode = 'safe' | 'exec' | 'staged';
+/**
+ * Whether a fetch that threw never sent its request: the connection was
+ * refused, the name did not resolve, or connecting timed out. Anything else
+ * (a reset, a timeout once connected, a runtime that names no cause) may
+ * have been delivered.
+ */
+export declare function neverSent(error: unknown, depth?: number): boolean;
+export declare function retryable(error: PrizedError, mode: RetryMode, method: RequestSpec['method']): boolean;
+export interface RequestSpec {
+    method: 'GET' | 'POST' | 'DELETE';
+    /** The URL, or one built per attempt from the ms left before `deadline`
+     *  (Infinity without one): a held request asks only for what is left. */
+    url: string | ((leftMs: number) => string);
+    json?: unknown;
+    body?: string | Uint8Array | ArrayBuffer | Blob;
+    contentType?: string;
+    headers?: Record<string, string>;
+    retry: RetryMode;
+    timeoutMs?: number;
+    /**
+     * Epoch ms (config.now()) bounding the whole call: each attempt's timeout
+     * is cut to what is left, and no retry starts past it.
+     */
+    deadline?: number | undefined;
+    signal?: AbortSignal | undefined;
+    sandboxId?: string | null;
+    /** How to read a 2xx body. Default `json`. */
+    read?: 'json' | 'bytes' | 'none';
+    /**
+     * Told of every attempt that failed (no answer, an error answer, or a 2xx
+     * that could not be read), before it is retried or thrown. A create or
+     * fork judges by them all whether it may have made sandboxes: the error
+     * thrown is only the last attempt's.
+     */
+    onAttemptFailed?: (error: PrizedError) => void;
+    /**
+     * What the request does in the sandbox (`exec`: a command unless given), so
+     * the error thrown once it may have arrived says whether that happened
+     * (outcome.ts). Given for a `safe` request (the keyed background start),
+     * its error says so too.
+     */
+    effect?: Effect;
+}
+export interface HttpResult {
+    status: number;
+    json: unknown;
+    bytes: Uint8Array | null;
+}
+/** The first retry's backoff; each later one doubles, up to MAX_BACKOFF_MS (jittered down to half). */
+export declare const BACKOFF_FIRST_MS = 500;
+export declare const MAX_BACKOFF_MS = 8000;
+/**
+ * The longest Retry-After the SDK waits for, the Python SDK's too: twice the
+ * longest the API asks for on a route the SDK calls (30 s, with 503
+ * sandbox_capacity; the edge asks for 1 s). A longer one is still on the
+ * error (`retryAfter`) if the retries run out.
+ */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+/**
+ * The bound on a call the caller gives no timeout (connect, list, templates,
+ * refresh, keepAlive), retries included: twice requestTimeoutMs, room for one
+ * attempt that runs out and the retries after it.
+ */
+export declare function callDeadline(config: Config): number;
+/**
+ * Whether request() ended because the call's deadline came first: no time
+ * was left, or the retry it was due could not start in time. A wait relabels
+ * only these as its own timeout; an attempt that got no answer while time
+ * was left is the API not answering, and is thrown as it is.
+ */
+export declare function cutByDeadline(error: unknown): error is PrizedError;
+/** The least room a wait leaves before its deadline for its last poll to be answered. */
+export declare const LAST_LOOK_MS = 100;
+/** The most: a slow read never makes a wait give up its last seconds. */
+export declare const LAST_LOOK_MAX_MS = 2000;
+/**
+ * A wait's polls, paced so the last goes out just before the deadline, with
+ * room for its answer: the slowest read of this wait so far plus
+ * LAST_LOOK_MS (at most LAST_LOOK_MAX_MS). Without it a wait whose last
+ * pause ran to the deadline gave up without looking, and one shorter than a
+ * poll interval never looked at all.
+ */
+export declare class Polls {
+    private readonly config;
+    private readonly deadline;
+    private lastLeft;
+    private sentAt;
+    private slowest;
+    constructor(config: Config, deadline: number);
+    private room;
+    /**
+     * How long to pause before the next poll: `delayMs`, cut so the poll goes
+     * out no later than the room it needs before the deadline (at once when
+     * less is left). null when the wait is over: the time is up, or the last
+     * look was taken (the previous poll went out with no more than that room).
+     */
+    pause(delayMs: number): number | null;
+    /** A poll is going out now. */
+    sent(): void;
+    /** Its answer came back. */
+    answered(): void;
+}
+/** Delay before retry number `attempt` (0-based): exponential with jitter. */
+export declare function backoffMs(config: Config, attempt: number): number;
+/**
+ * What an error answer (not a 2xx: request() judges those) says about
+ * whether the sandbox acted: `never` for the codes that prove the request
+ * never arrived, `maybe` for any other 5xx, null for a refusal (4xx), whose
+ * own words say what happened.
+ */
+export declare function outcomeOf(error: PrizedError): Outcome;
+/** One API or edge call, retried per `spec.retry`. Throws PrizedError. */
+export declare function request(config: Config, spec: RequestSpec): Promise<HttpResult>;