@prized/sdk 0.0.0-stage → 0.1.1

package/dist/cjs/errors.d.ts

@@ -0,0 +1,113 @@
+import type { ExecResult } from './types.js';
+/** Where a member makes an API key. */
+export declare const API_KEYS_URL = "https://prized.dev/dashboard/workspace/api-keys";
+/** Where a newcomer signs up (free credit, no card) and gets one. */
+export declare const SIGN_UP_URL = "https://prized.dev/onboarding/sandboxes";
+/** What a coding agent follows to sign its person up and get a key itself:
+ * their email address, then the 6-digit code Prized emails them. The SDK's
+ * own key errors name it; a refused key's 401 carries the API's own line
+ * (`signUp`), which follows the deployment. */
+export declare const AGENT_SIGN_UP_URL = "https://prized.dev/auth.md";
+/** The free tier's limits, and what lifts them. */
+export declare const FREE_TIER_URL = "https://prized.dev/docs/sandboxes#free-tier";
+/** The sentence an error with this code and no message of its own carries. */
+export declare function defaultMessage(code: string): string;
+export interface PrizedErrorInit {
+    /** The HTTP status, when an answer came back. */
+    status?: number | null;
+    /** The API's finer-grained reason, when it gave one. */
+    reason?: string | null;
+    sandboxId?: string | null;
+    /** The whole error document, when there was one. */
+    body?: Record<string, unknown> | null;
+    /** Seconds the API asked the caller to wait (Retry-After). */
+    retryAfter?: number | null;
+    /** The command's exit code, for an error that came after it ran. */
+    exitCode?: number | null;
+    cause?: unknown;
+}
+/**
+ * Every failure the SDK throws.
+ *
+ * - `status`: the HTTP status, or `null` when nothing came back (a network
+ *   failure, a wait that timed out, a refused argument).
+ * - `code`: the API's error string, e.g. `paid_balance_required`,
+ *   `insufficient_balance`, `sandbox_quota_exceeded`, `not_found`,
+ *   `rate_limited`; or one of the SDK's own: `missing_api_key`,
+ *   `invalid_api_key`, `invalid_argument`, `edge_unknown` (another
+ *   deployment's API named no command endpoint this SDK sends the key to),
+ *   `network_error`, `timeout`, `aborted`,
+ *   `bad_response`, `http_error`, `sandbox_error`, `sandbox_deleted`,
+ *   `command_failed`, `command_timeout` (thrown as CommandTimeoutError),
+ *   `output_read_failed` (thrown as OutputReadError).
+ * - `reason`: the finer-grained reason, when there is one (for
+ *   `sandbox_quota_exceeded` it names the quota: `sandbox_limit`,
+ *   `paused_limit`, `running_vcpu`, `running_memory`, `retained_disk`,
+ *   `max_runtime`; for `output_read_failed`, the code of the failure that
+ *   stopped the read).
+ * - `exitCode`: the command's exit code when the error came after it ran: a
+ *   `fullOutput` command whose output could not be read back
+ *   (`output_read_failed`, or `sandbox_deleted` when the sandbox was deleted
+ *   first). Don't run such a command again blindly. Null otherwise.
+ */
+export declare class PrizedError extends Error {
+    readonly status: number | null;
+    readonly code: string;
+    readonly reason: string | null;
+    readonly sandboxId: string | null;
+    readonly body: Record<string, unknown> | null;
+    readonly retryAfter: number | null;
+    readonly exitCode: number | null;
+    constructor(code: string, message?: string | null, init?: PrizedErrorInit);
+    toString(): string;
+}
+/**
+ * A command ran past its timeout and was killed (`code` is
+ * `command_timeout`). The sandbox answered as it does for any command that
+ * ends, so nothing is lost: `result` is that answer, with what the command
+ * printed before it was killed, `exitCode: -1` and `timedOut: true`.
+ * `timeoutMs` is the limit, or null when the SDK did not set one.
+ */
+export declare class CommandTimeoutError extends PrizedError {
+    readonly result: ExecResult;
+    readonly timeoutMs: number | null;
+    constructor(result: ExecResult, timeoutMs: number | null, sandboxId?: string | null);
+    /** What the command printed to stdout before it was killed. */
+    get stdout(): string;
+    /** What the command printed to stderr before it was killed. */
+    get stderr(): string;
+}
+export interface OutputReadErrorInit {
+    /** The failure that stopped the read: a download's error. */
+    cause: PrizedError;
+    exitCode: number;
+    stdoutPath: string;
+    stderrPath: string;
+}
+/**
+ * A `fullOutput` command ran, but its output could not be read back from the
+ * files it was copied to (`code` is `output_read_failed`). The command did
+ * run (`exitCode` is its exit code), so do not run it again blindly; and the
+ * sandbox is not known to be gone (a deleted one throws `sandbox_deleted`
+ * instead). `reason` is the code of the failure that stopped the read (say
+ * `not_found`, `network_error`), and `cause` is that error, with its HTTP
+ * status; `status` is null, as the command's own call succeeded. The output
+ * stays in the sandbox for an hour at `stdoutPath` and `stderrPath`: read it
+ * with files.read(), then remove their directory.
+ */
+export declare class OutputReadError extends PrizedError {
+    readonly exitCode: number;
+    readonly stdoutPath: string;
+    readonly stderrPath: string;
+    constructor(message: string, init: OutputReadErrorInit);
+}
+/** Retry-After as seconds: delta-seconds or an HTTP date. */
+export declare function parseRetryAfter(value: string | null, nowMs: number): number | null;
+/**
+ * The error document → a PrizedError. Two envelopes are read: today's flat
+ * `{ "error": "code", "message"?, "reason"?, "field"? }` and the nested
+ * `{ "error": { "code", "message" } }`. Anything else (a proxy's HTML page)
+ * becomes `http_error` with the status. `path` is the request's URL path,
+ * which tells a file call's 404 from a sandbox's.
+ */
+export declare function errorFromResponse(status: number, text: string, retryAfter: number | null, sandboxId: string | null, path?: string): PrizedError;

package/dist/cjs/errors.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputReadError = exports.CommandTimeoutError = exports.PrizedError = exports.FREE_TIER_URL = exports.AGENT_SIGN_UP_URL = exports.SIGN_UP_URL = exports.API_KEYS_URL = void 0;
+exports.defaultMessage = defaultMessage;
+exports.parseRetryAfter = parseRetryAfter;
+exports.errorFromResponse = errorFromResponse;
+/** Where a member makes an API key. */
+exports.API_KEYS_URL = 'https://prized.dev/dashboard/workspace/api-keys';
+/** Where a newcomer signs up (free credit, no card) and gets one. */
+exports.SIGN_UP_URL = 'https://prized.dev/onboarding/sandboxes';
+/** What a coding agent follows to sign its person up and get a key itself:
+ * their email address, then the 6-digit code Prized emails them. The SDK's
+ * own key errors name it; a refused key's 401 carries the API's own line
+ * (`signUp`), which follows the deployment. */
+exports.AGENT_SIGN_UP_URL = 'https://prized.dev/auth.md';
+const AGENT_SIGN_UP = `No Prized account yet? If you are an agent, you can sign your person up with their email and a 6-digit code: follow ${exports.AGENT_SIGN_UP_URL}`;
+/** The free tier's limits, and what lifts them. */
+exports.FREE_TIER_URL = 'https://prized.dev/docs/sandboxes#free-tier';
+/** A sentence for the codes a caller is most likely to meet, used when the
+ * answer carries no `message` of its own. */
+const MESSAGES = {
+    // The SDK's own codes.
+    missing_api_key: `No API key: pass apiKey or set PRIZED_API_KEY. New to Prized? ${exports.SIGN_UP_URL} signs you up and makes one, or, if you are an agent, you can sign your person up with their email and a 6-digit code: follow ${exports.AGENT_SIGN_UP_URL}, keep the key file it writes, and pass that key as apiKey at run time, never in source. Otherwise make one at ${exports.API_KEYS_URL}.`,
+    invalid_api_key: `The API key has characters no key has (the docs' placeholder, or a stray character?); copy it again from ${exports.API_KEYS_URL}. ${AGENT_SIGN_UP}`,
+    invalid_argument: 'An argument was not valid.',
+    edge_unknown: 'The API named no command endpoint this SDK trusts; pass edgeUrl for that deployment.',
+    network_error: 'Could not reach the Prized API.',
+    timeout: 'Timed out.',
+    aborted: 'The operation was aborted.',
+    bad_response: 'The API answered with something the SDK could not read.',
+    http_error: 'The API answered with an error the SDK does not recognise.',
+    unexpected_redirect: 'The API answered with a redirect; the SDK does not follow redirects with your key.',
+    sandbox_error: 'The sandbox failed.',
+    sandbox_deleted: 'The sandbox was deleted.',
+    command_failed: 'The command failed in the sandbox.',
+    command_timeout: 'The command ran past its timeout and was killed.',
+    output_read_failed: 'The command ran, but its output could not be read back from the sandbox.',
+    not_directory: 'Not a directory.',
+    // The API's and the exec edge's codes.
+    unauthorized: `The API key was refused. Check that it is a live key from ${exports.API_KEYS_URL}.`,
+    token_expired: `The API key has expired. Make a new one at ${exports.API_KEYS_URL}.`,
+    key_access_denied: 'This API key does not have the Sandboxes permission it needs.',
+    not_found: 'Not found (or not visible to this API key).',
+    bad_request: 'The request was not valid.',
+    unknown_field: 'The request carried a field the API does not accept.',
+    template_not_found: 'No such template. Sandbox.templates() lists the ones you can use.',
+    template_inactive: 'That template is no longer offered. Sandbox.templates() lists the current ones.',
+    invalid_resources: 'The requested shape is outside what the template allows.',
+    invalid_max_runtime: 'maxRuntimeMin must be a positive whole number of minutes.',
+    paid_balance_required: 'Sandboxes need a paid balance: add funds or pick a paid plan, then retry. Free trial credit cannot start a sandbox.',
+    insufficient_balance: 'The workspace balance is empty. Add funds, then retry.',
+    sandbox_quota_exceeded: 'The workspace is at a sandbox quota. Delete sandboxes you no longer need (paused ones still count), then retry.',
+    sandboxes_disabled: 'Sandboxes are not available right now.',
+    sandbox_create_disabled: 'Creating sandboxes is not available right now.',
+    sandbox_fork_disabled: 'Forking is paused for maintenance. Retry later.',
+    idempotency_conflict: 'This idempotency key was already used for a different request.',
+    invalid_idempotency_key: 'Idempotency keys are 1 to 128 printable characters with no spaces.',
+    rate_limited: 'Too many requests. Slow down and retry.',
+    sandbox_not_running: 'The sandbox is not running and could not be woken (it is resizing, failed, or being deleted).',
+    sandbox_not_ready: 'The sandbox did not finish starting in time. Nothing ran; retry.',
+    sandbox_unreachable: 'The sandbox did not answer. If this was a command, it may or may not have run.',
+    resolve_failed: 'The exec service could not look the sandbox up. Retry shortly.',
+    parent_not_running: 'Only a running or paused sandbox can be forked.',
+    parent_not_forkable: 'This sandbox cannot be forked.',
+    fork_capacity: "The parent sandbox's machine has no room for that many copies right now.",
+    fork_unsupported_host: "The parent sandbox's machine cannot start copies of it. Create a new sandbox, set it up again, and fork that one.",
+    invalid_count: 'Fork count is out of range.',
+    body_too_large: 'The request body is over the size limit.',
+    file_too_large: 'The file is over the 100 MiB transfer limit.',
+    missing_path: 'A file path is required.',
+    path_outside_root: 'File paths must be inside the sandbox user\'s home directory (/home/prized).',
+    path_not_absolute: 'File paths must be absolute.',
+    invalid_path: 'File paths may not contain ".." or NUL.',
+    symlink_not_allowed: 'File transfers cannot follow a symbolic link in this path (one leading outside /home/prized, or a loop).',
+    not_regular_file: 'Only regular files can be downloaded.',
+    permission_denied: 'Permission denied in the sandbox.',
+    missing_command: 'The command is empty.',
+    cwd_not_absolute: 'cwd must be an absolute path.',
+    bad_env: 'An environment variable name or value is not valid.',
+    spawn_failed: 'The command could not be started (is cwd a directory that exists?).',
+};
+/** The sentence an error with this code and no message of its own carries. */
+function defaultMessage(code) {
+    return MESSAGES[code] || code.replace(/_/g, ' ');
+}
+/**
+ * Every failure the SDK throws.
+ *
+ * - `status`: the HTTP status, or `null` when nothing came back (a network
+ *   failure, a wait that timed out, a refused argument).
+ * - `code`: the API's error string, e.g. `paid_balance_required`,
+ *   `insufficient_balance`, `sandbox_quota_exceeded`, `not_found`,
+ *   `rate_limited`; or one of the SDK's own: `missing_api_key`,
+ *   `invalid_api_key`, `invalid_argument`, `edge_unknown` (another
+ *   deployment's API named no command endpoint this SDK sends the key to),
+ *   `network_error`, `timeout`, `aborted`,
+ *   `bad_response`, `http_error`, `sandbox_error`, `sandbox_deleted`,
+ *   `command_failed`, `command_timeout` (thrown as CommandTimeoutError),
+ *   `output_read_failed` (thrown as OutputReadError).
+ * - `reason`: the finer-grained reason, when there is one (for
+ *   `sandbox_quota_exceeded` it names the quota: `sandbox_limit`,
+ *   `paused_limit`, `running_vcpu`, `running_memory`, `retained_disk`,
+ *   `max_runtime`; for `output_read_failed`, the code of the failure that
+ *   stopped the read).
+ * - `exitCode`: the command's exit code when the error came after it ran: a
+ *   `fullOutput` command whose output could not be read back
+ *   (`output_read_failed`, or `sandbox_deleted` when the sandbox was deleted
+ *   first). Don't run such a command again blindly. Null otherwise.
+ */
+class PrizedError extends Error {
+    status;
+    code;
+    reason;
+    sandboxId;
+    body;
+    retryAfter;
+    exitCode;
+    constructor(code, message, init = {}) {
+        super(message || defaultMessage(code), init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = 'PrizedError';
+        this.code = code;
+        this.status = init.status ?? null;
+        this.reason = init.reason ?? null;
+        this.sandboxId = init.sandboxId ?? null;
+        this.body = init.body ?? null;
+        this.retryAfter = init.retryAfter ?? null;
+        this.exitCode = init.exitCode ?? null;
+    }
+    toString() {
+        const head = this.status === null ? this.code : `${this.status} ${this.code}`;
+        const extra = this.reason ? ` (${this.reason})` : '';
+        return `${this.name}: ${head}${extra}: ${this.message}`;
+    }
+}
+exports.PrizedError = PrizedError;
+/**
+ * A command ran past its timeout and was killed (`code` is
+ * `command_timeout`). The sandbox answered as it does for any command that
+ * ends, so nothing is lost: `result` is that answer, with what the command
+ * printed before it was killed, `exitCode: -1` and `timedOut: true`.
+ * `timeoutMs` is the limit, or null when the SDK did not set one.
+ */
+class CommandTimeoutError extends PrizedError {
+    result;
+    timeoutMs;
+    constructor(result, timeoutMs, sandboxId = null) {
+        const limit = timeoutMs === null ? 'its timeout' : `its ${timeoutMs} ms timeout`;
+        super('command_timeout', `The command ran past ${limit} and was killed; this error's result has what it printed. ` +
+            'Pass a larger timeoutMs (0 for no limit) to give it longer.', { sandboxId });
+        this.name = 'CommandTimeoutError';
+        this.result = result;
+        this.timeoutMs = timeoutMs;
+    }
+    /** What the command printed to stdout before it was killed. */
+    get stdout() {
+        return this.result.stdout;
+    }
+    /** What the command printed to stderr before it was killed. */
+    get stderr() {
+        return this.result.stderr;
+    }
+}
+exports.CommandTimeoutError = CommandTimeoutError;
+/**
+ * A `fullOutput` command ran, but its output could not be read back from the
+ * files it was copied to (`code` is `output_read_failed`). The command did
+ * run (`exitCode` is its exit code), so do not run it again blindly; and the
+ * sandbox is not known to be gone (a deleted one throws `sandbox_deleted`
+ * instead). `reason` is the code of the failure that stopped the read (say
+ * `not_found`, `network_error`), and `cause` is that error, with its HTTP
+ * status; `status` is null, as the command's own call succeeded. The output
+ * stays in the sandbox for an hour at `stdoutPath` and `stderrPath`: read it
+ * with files.read(), then remove their directory.
+ */
+class OutputReadError extends PrizedError {
+    exitCode;
+    stdoutPath;
+    stderrPath;
+    constructor(message, init) {
+        const { cause } = init;
+        super('output_read_failed', message, { reason: cause.code, sandboxId: cause.sandboxId, cause, exitCode: init.exitCode });
+        this.name = 'OutputReadError';
+        this.exitCode = init.exitCode;
+        this.stdoutPath = init.stdoutPath;
+        this.stderrPath = init.stderrPath;
+    }
+}
+exports.OutputReadError = OutputReadError;
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+/**
+ * fork_capacity's sentence from the answer's `fits` (the API's own, worded
+ * for the SDK), for an answer without one: fewer copies help only when some
+ * fit.
+ */
+function forkCapacityMessage(fits) {
+    if (typeof fits !== 'number' || !Number.isInteger(fits) || fits < 0)
+        return null;
+    const newParent = 'start a new sandbox (it starts fresh) and fork that one, keeping the parent until it runs';
+    const atLimit = 'The new sandbox and each copy count toward your sandbox limit: at it, delete sandboxes you no longer need ' +
+        'and wait until they are gone (copy out what you need first, and keep the parent while a copy forked from it ' +
+        'is still starting), or, on the free tier, top up to raise it.';
+    if (fits === 0) {
+        return `The parent sandbox's machine is full, so no copy of it fits right now. Try again later, or ${newParent}. ${atLimit}`;
+    }
+    const copies = fits === 1 ? '1 more copy' : `${fits} more copies`;
+    return `The parent sandbox's machine has room for ${copies} right now. Fork ${fits} or fewer, or ${newParent}. ${atLimit}`;
+}
+/** The unit of a free-tier refusal's `limit`, by its reason (or, for a shape, its field): the API's own units. */
+const FREE_UNITS = {
+    sandbox_limit: 'sandboxes at once',
+    paused_limit: 'paused sandboxes',
+    running_vcpu: 'vCPU running at once',
+    running_memory: 'MB of memory running at once',
+    retained_disk: 'GB of disk',
+    max_runtime: 'minutes of run time',
+    vcpu: 'vCPU per sandbox',
+    memoryMb: 'MB of memory per sandbox',
+};
+/** A free-tier refusal's sentence: what refused it, and what lifts it. */
+function freeTierMessage(code, message, reason, limit) {
+    if (message === null && code === 'invalid_resources')
+        message = "The sandbox's shape is over the free tier's limit for one sandbox.";
+    else if (message === null && reason === 'max_runtime')
+        message = 'The run time asked for is longer than the free tier allows.';
+    const base = message ?? MESSAGES[code] ?? code.replace(/_/g, ' ');
+    const unit = reason === null ? undefined : FREE_UNITS[reason];
+    const which = unit !== undefined && typeof limit === 'number' && Number.isInteger(limit) ? ` (${limit} ${unit})` : '';
+    return `${base} It is a free-tier limit${which}: a top-up or a plan lifts it (${exports.FREE_TIER_URL}).`;
+}
+/**
+ * A 404 about a sandbox the caller named: most often one deleted when its
+ * run time ended. A file call's 404 may be the file instead, and the edge
+ * answers both the same way.
+ */
+function notFoundMessage(sandboxId, path) {
+    const gone = 'it was deleted, or its run time ended (60 minutes of running on the free tier)';
+    if (path.includes('/files/'))
+        return `Not found: no such file in sandbox ${sandboxId}, or the sandbox is gone (${gone}).`;
+    return `No sandbox ${sandboxId} for this API key: ${gone}, or it is in another workspace. Sandbox.create() makes a new one.`;
+}
+/** Retry-After as seconds: delta-seconds or an HTTP date. */
+function parseRetryAfter(value, nowMs) {
+    if (value === null || value.trim() === '')
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : Math.max(0, (at - nowMs) / 1000);
+}
+/**
+ * The error document → a PrizedError. Two envelopes are read: today's flat
+ * `{ "error": "code", "message"?, "reason"?, "field"? }` and the nested
+ * `{ "error": { "code", "message" } }`. Anything else (a proxy's HTML page)
+ * becomes `http_error` with the status. `path` is the request's URL path,
+ * which tells a file call's 404 from a sandbox's.
+ */
+function errorFromResponse(status, text, retryAfter, sandboxId, path = '') {
+    let doc = null;
+    try {
+        const parsed = text ? JSON.parse(text) : null;
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            doc = parsed;
+        }
+    }
+    catch {
+        // Not JSON: handled below.
+    }
+    let code = null;
+    let message = null;
+    if (doc) {
+        const envelope = doc.error;
+        if (typeof envelope === 'string' && envelope !== '') {
+            code = envelope;
+        }
+        else if (envelope !== null && typeof envelope === 'object' && !Array.isArray(envelope)) {
+            code = stringField(envelope, 'code');
+            message = stringField(envelope, 'message');
+        }
+        message = message ?? stringField(doc, 'message');
+    }
+    if (code === null) {
+        const snippet = text.replace(/\s+/g, ' ').trim().slice(0, 160);
+        return new PrizedError('http_error', `HTTP ${status}${snippet ? `: ${snippet}` : ''}`, {
+            status,
+            sandboxId,
+            retryAfter,
+        });
+    }
+    if (message === null && code === 'fork_capacity' && doc)
+        message = forkCapacityMessage(doc.fits);
+    if (message === null && code === 'not_found' && status === 404 && sandboxId !== null)
+        message = notFoundMessage(sandboxId, path);
+    const reason = doc ? stringField(doc, 'reason') ?? stringField(doc, 'field') ?? stringField(doc, 'detail') : null;
+    if (doc && doc.tier === 'free' && !(message ?? '').includes('free tier'))
+        message = freeTierMessage(code, message, reason, doc.limit);
+    // A refused key's 401 may say how an agent signs its person up (the API
+    // sends it where agent sign-in answers, with that deployment's address).
+    const signUp = code === 'unauthorized' && doc ? stringField(doc, 'signUp') : null;
+    if (signUp !== null)
+        message = `${message ?? defaultMessage(code)} ${signUp.slice(0, 300)}`;
+    return new PrizedError(code, message, { status, reason, sandboxId, body: doc, retryAfter });
+}

package/dist/cjs/files.d.ts

@@ -0,0 +1,101 @@
+import { type Toolbox } from './toolbox.js';
+import type { FileInfo, WriteInfo } from './types.js';
+/** What files.write accepts. */
+export type FileData = string | Uint8Array | ArrayBuffer | Blob;
+/** Options for files.write() and files.upload(). */
+export interface WriteOptions {
+    /**
+     * The file's permission bits, 0 to 0o777 (`0o755` for a script). Without
+     * it, a file that is replaced keeps its mode, and a new file gets the
+     * sandbox's default (0600 in prized-base-v1 and prized-agent-v1).
+     */
+    mode?: number;
+}
+/**
+ * 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 declare const FILE_TIMEOUT_MS: number;
+/** The publish script's own exits (the Python SDK's too). */
+export declare const EXIT_TARGET_IS_LINK = 47;
+export declare const EXIT_TARGET_NOT_REGULAR = 48;
+/**
+ * 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 declare function stagingFor(target: string, suffix?: string): {
+    clean: string;
+    staging: string;
+} | null;
+/**
+ * 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 declare function publishScript(staging: string, target: string, mode: number | null): string;
+/** File operations on one sandbox. Paths are absolute, or relative to /home/prized/work. */
+export declare class Files {
+    private readonly toolbox;
+    /** @internal */
+    constructor(toolbox: Toolbox);
+    private url;
+    /** A file's contents as UTF-8 text. */
+    read(path: string): Promise<string>;
+    /** A file's contents as bytes (at most 100 MiB). */
+    readBytes(path: string): Promise<Uint8Array>;
+    /**
+     * 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).
+     */
+    write(path: string, data: FileData, options?: WriteOptions): Promise<WriteInfo>;
+    /**
+     * 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.
+     */
+    private send;
+    /**
+     * 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.
+     */
+    private discard;
+    private chmod;
+    /** One of a write's own commands, run in the home, which is always there (the workspace may not be). */
+    private run;
+    /** A directory's entries, sorted by name (default: /home/prized/work). */
+    list(path?: string): Promise<FileInfo[]>;
+    /** Whether a path exists (a file, a directory, or a link, even a dangling one). */
+    exists(path: string): Promise<boolean>;
+    /** Remove a file, or a directory tree with `recursive: true`. A missing path is not an error. */
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Copy a local file into the sandbox (Node, Bun, Deno), as write() does. */
+    upload(localPath: string, remotePath: string, options?: WriteOptions): Promise<WriteInfo>;
+    /** Copy a file out of the sandbox to a local path (Node, Bun, Deno). Returns the byte count. */
+    download(remotePath: string, localPath: string): Promise<number>;
+}