@prized/sdk 0.1.0 → 0.1.2

package/dist/esm/commands.d.ts

@@ -19,20 +19,34 @@ export declare const MAX_BLOCKING_EXEC_MS = 240000;
 export declare function ridesOut(error: PrizedError): boolean;
 /**
  * The failed polls of a wait that rides out an outage of up to `windowMs`
- * (exec's pollOutageMs), from when the first poll's retries ran out: polled
- * again with backoff, each poll and its retries ending before the last look,
- * which goes out LAST_LOOK_MAX_MS before the window's end (half the window,
- * for one shorter than twice that) with room for its own retries. So an
- * outage that ends inside the window is always seen to end. The Python
- * SDK's Outage.
+ * (pollOutageMs), from when the first poll's retries ran out, and, while the
+ * command runs, never past the wait's own deadline (`waitDeadline`, epoch
+ * ms; null for none): polled again with backoff, each poll and its retries
+ * ending before the last look, which goes out LAST_LOOK_MAX_MS before the
+ * window's end (half the window, for one shorter than twice that) with room
+ * for its own retries. So an outage that ends inside the window is always
+ * seen to end. The Python SDK's Outage.
  */
 export declare class Outage {
     private readonly windowMs;
+    private readonly waitDeadline;
     private end;
     private last;
     private tries;
-    private readonly room;
-    constructor(windowMs: number);
+    private room;
+    private finished;
+    constructor(windowMs: number, waitDeadline?: number | null);
+    /** The command has ended: draining its output, and an outage meanwhile, are not held to the deadline. */
+    finish(): void;
+    /**
+     * Whether a wait's failed poll (`error`, at `now`; `cut`: its bound cut it
+     * short) means the wait's own time ran out: its deadline cut the poll
+     * short while the command ran, with no outage being ridden out, so the
+     * command was still running when last seen. With no window, any timeout
+     * while it runs says so, as it always has. Never once the command has
+     * ended. The Python SDK's Outage.ran_out.
+     */
+    ranOut(error: PrizedError, now: number, cut: boolean): boolean;
     /** The bound on a poll sent `now`: undefined unless polls are failing; else the last look's start, or the window's end for the last look. */
     deadline(now: number): number | undefined;
     /** A poll was answered: the outage, if any, is over. */
@@ -90,16 +104,33 @@ export interface ExecOptions {
      * its polls fail (no answer, a 5xx, a rate limit), in ms, before it gives
      * up and stops the command. Default: the client's `pollOutageMs`
      * (120 000). A refused key, or an answer that settles the run (the
-     * sandbox deleted or not running, the run gone), stops it at once.
+     * sandbox deleted or not running, the run gone), stops it at once. The
+     * start of a background, streamed or long command is sent again for as
+     * long (a resend finds the first start, so the command runs once).
      */
     pollOutageMs?: number;
 }
 export interface WaitOptions {
-    /** Stop waiting after this many ms (the command keeps running). Default: no limit. */
+    /**
+     * Stop waiting after this many ms (the command keeps running). Default: no
+     * limit. Once the command has ended, reading the rest of its output is not
+     * held to it.
+     */
     timeoutMs?: number;
     onStdout?: (chunk: string) => void;
     onStderr?: (chunk: string) => void;
     signal?: AbortSignal;
+    /**
+     * How long the wait keeps polling while its polls fail (no answer, a 5xx,
+     * a rate limit), in ms, before it gives up and throws what the polls met.
+     * While the command runs, never past `timeoutMs`. Default: the client's
+     * `pollOutageMs` (120 000).
+     * `0` gives up once one poll's retries run out. A refused key, or an
+     * answer that settles the run (the sandbox deleted or not running, the
+     * run gone), ends the wait at once. Giving up stops nothing: the command
+     * keeps running, and wait() can be called again.
+     */
+    pollOutageMs?: number;
 }
 export interface CommandStatus {
     running: boolean;
@@ -136,15 +167,17 @@ export declare class CommandHandle {
      * `onStdout`/`onStderr` receive the output as it arrives, from the start.
      * A `timeoutMs` here bounds the wait only; the command keeps running. If
      * the command ran past its own timeout (the one given to exec), it was
-     * killed and this throws CommandTimeoutError with what it printed.
+     * killed and this throws CommandTimeoutError with what it printed. While
+     * polls fail (a dropped connection, a 5xx), it keeps polling for up to
+     * `pollOutageMs` (the client's, 120 000 by default) before it throws.
      */
     wait(options?: WaitOptions): Promise<ExecResult>;
     /**
      * @internal wait() without the timeout check: exec cleans up before it
-     * throws. `outageMs` (exec's pollOutageMs; a wait with no limit only):
-     * how long polls may fail before the wait gives up (Outage).
+     * throws. `outageMs` (pollOutageMs): how long polls may fail before the
+     * wait gives up (Outage), never past the wait's own deadline.
      */
-    waitRaw(options?: WaitOptions, outageMs?: number): Promise<ExecResult>;
+    waitRaw(options: WaitOptions, outageMs: number): Promise<ExecResult>;
     private waitTimeout;
     private result;
     /**

package/dist/esm/commands.js

@@ -3,7 +3,7 @@
 import { CommandTimeoutError, PrizedError } from './errors.js';
 import { backoffMs, cutByDeadline, LAST_LOOK_MAX_MS, MAX_RETRY_AFTER_MS, Polls, validOutage } from './http.js';
 import { abandonScript, cleanupScript, commandText, killScript, NO_PID_EXIT, pollScript, RUN_ID_RE, sandboxPath, SIGNALS, startScript, } from './shell.js';
-import { mayHaveActed, pollFailed, runAborted, signalEffect, startAbandoned, startEffect, withOutcome } from './outcome.js';
+import { mayHaveActed, pollFailed, runAborted, signalEffect, startAbandoned, startEffect, startGaveUp, withAbort, withOutcome } from './outcome.js';
 import { execFullOutput } from './output.js';
 import { helperExec, rawExec } from './toolbox.js';
 /** The timeout a command gets when the call names none. */
@@ -65,22 +65,42 @@ export function ridesOut(error) {
 }
 /**
  * The failed polls of a wait that rides out an outage of up to `windowMs`
- * (exec's pollOutageMs), from when the first poll's retries ran out: polled
- * again with backoff, each poll and its retries ending before the last look,
- * which goes out LAST_LOOK_MAX_MS before the window's end (half the window,
- * for one shorter than twice that) with room for its own retries. So an
- * outage that ends inside the window is always seen to end. The Python
- * SDK's Outage.
+ * (pollOutageMs), from when the first poll's retries ran out, and, while the
+ * command runs, never past the wait's own deadline (`waitDeadline`, epoch
+ * ms; null for none): polled again with backoff, each poll and its retries
+ * ending before the last look, which goes out LAST_LOOK_MAX_MS before the
+ * window's end (half the window, for one shorter than twice that) with room
+ * for its own retries. So an outage that ends inside the window is always
+ * seen to end. The Python SDK's Outage.
  */
 export class Outage {
     windowMs;
+    waitDeadline;
     end = null;
     last = null;
     tries = 0;
-    room;
-    constructor(windowMs) {
+    room = 0;
+    finished = false;
+    constructor(windowMs, waitDeadline = null) {
         this.windowMs = windowMs;
-        this.room = Math.min(LAST_LOOK_MAX_MS, windowMs / 2);
+        this.waitDeadline = waitDeadline;
+    }
+    /** The command has ended: draining its output, and an outage meanwhile, are not held to the deadline. */
+    finish() {
+        this.finished = true;
+    }
+    /**
+     * Whether a wait's failed poll (`error`, at `now`; `cut`: its bound cut it
+     * short) means the wait's own time ran out: its deadline cut the poll
+     * short while the command ran, with no outage being ridden out, so the
+     * command was still running when last seen. With no window, any timeout
+     * while it runs says so, as it always has. Never once the command has
+     * ended. The Python SDK's Outage.ran_out.
+     */
+    ranOut(error, now, cut) {
+        if (this.waitDeadline === null || this.finished || error.code !== 'timeout')
+            return false;
+        return this.windowMs <= 0 || (this.end === null && (cut || now >= this.waitDeadline));
     }
     /** The bound on a poll sent `now`: undefined unless polls are failing; else the last look's start, or the window's end for the last look. */
     deadline(now) {
@@ -104,7 +124,10 @@ export class Outage {
     failed(error, sentAt, now, cut, backoff) {
         if (this.windowMs <= 0 || !ridesOut(error))
             return { pause: null, failure: error };
-        this.end ??= now + this.windowMs;
+        if (this.end === null) {
+            this.end = Math.min(now + this.windowMs, this.finished || this.waitDeadline === null ? Infinity : this.waitDeadline);
+            this.room = Math.max(0, Math.min(LAST_LOOK_MAX_MS, (this.end - now) / 2));
+        }
         const met = error.cause instanceof PrizedError ? error.cause : null;
         if (!cut) {
             this.last = error;
@@ -272,17 +295,20 @@ export class CommandHandle {
      * `onStdout`/`onStderr` receive the output as it arrives, from the start.
      * A `timeoutMs` here bounds the wait only; the command keeps running. If
      * the command ran past its own timeout (the one given to exec), it was
-     * killed and this throws CommandTimeoutError with what it printed.
+     * killed and this throws CommandTimeoutError with what it printed. While
+     * polls fail (a dropped connection, a 5xx), it keeps polling for up to
+     * `pollOutageMs` (the client's, 120 000 by default) before it throws.
      */
     async wait(options = {}) {
-        return finished(await this.waitRaw(options), this.timeoutMs, this.sandboxId);
+        const outageMs = validOutage(options.pollOutageMs) ?? this.toolbox.config.pollOutageMs;
+        return finished(await this.waitRaw(options, outageMs), this.timeoutMs, this.sandboxId);
     }
     /**
      * @internal wait() without the timeout check: exec cleans up before it
-     * throws. `outageMs` (exec's pollOutageMs; a wait with no limit only):
-     * how long polls may fail before the wait gives up (Outage).
+     * throws. `outageMs` (pollOutageMs): how long polls may fail before the
+     * wait gives up (Outage), never past the wait's own deadline.
      */
-    async waitRaw(options = {}, outageMs = 0) {
+    async waitRaw(options, outageMs) {
         const config = this.toolbox.config;
         const deadline = options.timeoutMs ? config.now() + options.timeoutMs : null;
         const out = new StreamReader(options.onStdout);
@@ -290,7 +316,7 @@ export class CommandHandle {
         let delay = POLL_MIN_MS;
         let finished = false;
         const polls = deadline === null ? null : new Polls(config, deadline);
-        const outage = new Outage(deadline === null ? outageMs : 0);
+        const outage = new Outage(outageMs, deadline);
         for (;;) {
             let report;
             const sentAt = config.now();
@@ -305,13 +331,15 @@ export class CommandHandle {
                 polls?.answered();
             }
             catch (error) {
-                if (deadline !== null && error instanceof PrizedError && error.code === 'timeout')
+                const now = config.now();
+                if (error instanceof PrizedError && outage.ranOut(error, now, cutByDeadline(error))) {
                     throw this.waitTimeout(options.timeoutMs);
+                }
                 let failure = error;
                 if (error instanceof PrizedError && !options.signal?.aborted) {
                     // A dropped connection, an edge restarting: the command may be
                     // fine. Poll again until the window runs out, then give up.
-                    const step = outage.failed(error, sentAt, config.now(), cutByDeadline(error), (tries) => backoffMs(config, tries));
+                    const step = outage.failed(error, sentAt, now, cutByDeadline(error), (tries) => backoffMs(config, tries));
                     if (step.pause !== null) {
                         await config.sleep(step.pause, options.signal);
                         continue;
@@ -323,8 +351,10 @@ export class CommandHandle {
                 throw failure;
             }
             outage.answered();
-            if (report.state !== 'running')
+            if (report.state !== 'running') {
                 finished = true;
+                outage.finish();
+            }
             out.push(report.stdout);
             err.push(report.stderr);
             const more = (report.stdout.length > 0 && out.offset < report.outSize) ||
@@ -440,7 +470,48 @@ async function cleanupOnceGone(toolbox, id) {
         }
     }
 }
-async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, unbuffered) {
+/**
+ * Send a start script. It is keyed by a run id the SDK chose, so a resend
+ * finds the first start instead of starting the command twice. Once one
+ * copy's retries run out, it is sent again through an outage of up to
+ * `outageMs` (pollOutageMs), paced as a wait's polls are (Outage): an edge
+ * that restarts mid-start does not cost the command, as it does not cost a
+ * running one its wait. Each copy's error counts the copies before it
+ * (`acted`), so one that gives up says the command may have started when any
+ * copy may have reached the sandbox. The Python SDK's _send_start.
+ */
+async function sendStart(toolbox, req, signal, outageMs) {
+    const config = toolbox.config;
+    const outage = new Outage(outageMs);
+    // Whether an earlier copy may have reached the sandbox: an abort between
+    // copies then says the command may have started, else that it never did.
+    let acted = false;
+    const aborted = (cause) => withAbort(new PrizedError('aborted', null, { sandboxId: toolbox.sandboxId, cause }), startEffect(), acted ? 'maybe' : 'never');
+    for (;;) {
+        const sentAt = config.now();
+        try {
+            return await rawExec(toolbox, req, { retry: 'safe', signal, deadline: outage.deadline(sentAt), effect: startEffect(), acted });
+        }
+        catch (error) {
+            if (!(error instanceof PrizedError))
+                throw error;
+            acted = acted || mayHaveActed(error);
+            if (signal?.aborted)
+                throw error;
+            const step = outage.failed(error, sentAt, config.now(), cutByDeadline(error), (tries) => backoffMs(config, tries));
+            // What a copy met, not the window's cut.
+            if (step.pause === null)
+                throw step.failure === error ? error : startGaveUp(step.failure, acted);
+            try {
+                await config.sleep(step.pause, signal);
+            }
+            catch (abort) {
+                throw abort instanceof PrizedError && abort.code === 'aborted' ? aborted(step.failure) : abort;
+            }
+        }
+    }
+}
+async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, unbuffered, outageMs) {
     // Nothing sent yet: nothing to stop.
     if (signal?.aborted)
         throw withOutcome(new PrizedError('aborted', null, { sandboxId: toolbox.sandboxId }), startEffect(), 'never');
@@ -452,10 +523,7 @@ async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, un
     // Launched, but no pid came within the start's own wait: it may yet run.
     let unsettled = false;
     try {
-        const result = await rawExec(toolbox, { command: startScript(id, command, timeoutMs === null ? null : timeoutMs / 1000, unbuffered), cwd, env, timeoutMs: 60_000 }, 
-        // Keyed by a run id this call chose, so a resend finds the first start
-        // instead of starting the command twice.
-        { retry: 'safe', signal, effect: startEffect() });
+        const result = await sendStart(toolbox, { command: startScript(id, command, timeoutMs === null ? null : timeoutMs / 1000, unbuffered), cwd, env, timeoutMs: 60_000 }, signal, outageMs);
         pid = Number(result.stdout.trim());
         if (result.exitCode !== 0 || !Number.isInteger(pid) || pid <= 0) {
             unsettled = result.exitCode === NO_PID_EXIT;
@@ -501,7 +569,7 @@ export async function execCommand(toolbox, command, options = {}) {
     const cwd = options.cwd === undefined ? undefined : sandboxPath(options.cwd);
     if (options.background) {
         const limit = options.timeoutMs ? options.timeoutMs : null;
-        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, true);
+        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, true, outageMs);
         handle.timeoutMs = limit;
         return handle;
     }
@@ -509,7 +577,7 @@ export async function execCommand(toolbox, command, options = {}) {
     const streamed = options.onStdout !== undefined || options.onStderr !== undefined;
     if (streamed || timeoutMs === 0 || timeoutMs > MAX_BLOCKING_EXEC_MS) {
         const limit = timeoutMs === 0 ? null : timeoutMs;
-        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, streamed);
+        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, streamed, outageMs);
         const waitOptions = {};
         if (options.onStdout)
             waitOptions.onStdout = options.onStdout;

package/dist/esm/errors.d.ts

@@ -3,6 +3,11 @@ import type { ExecResult } from './types.js';
 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. */
@@ -17,6 +22,8 @@ export interface PrizedErrorInit {
     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;
 }
 /**
@@ -27,13 +34,21 @@ export interface PrizedErrorInit {
  * - `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`, `network_error`, `timeout`, `aborted`,
+ *   `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).
+ *   `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`).
+ *   `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;
@@ -42,6 +57,7 @@ export declare class PrizedError extends Error {
     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;
 }
@@ -61,6 +77,30 @@ export declare class CommandTimeoutError extends PrizedError {
     /** 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;
 /**

package/dist/esm/errors.js

@@ -2,15 +2,22 @@
 export const API_KEYS_URL = 'https://prized.dev/dashboard/workspace/api-keys';
 /** Where a newcomer signs up (free credit, no card) and gets one. */
 export 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 const 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 ${AGENT_SIGN_UP_URL}`;
 /** The free tier's limits, and what lifts them. */
 export const 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? ${SIGN_UP_URL} signs you up and makes one; otherwise make one at ${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 ${API_KEYS_URL}.`,
+    missing_api_key: `No API key: pass apiKey or set PRIZED_API_KEY. New to Prized? ${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 ${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 ${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 ${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.',
@@ -21,6 +28,7 @@ const MESSAGES = {
     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 ${API_KEYS_URL}.`,
@@ -77,13 +85,21 @@ export function defaultMessage(code) {
  * - `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`, `network_error`, `timeout`, `aborted`,
+ *   `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).
+ *   `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`).
+ *   `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 class PrizedError extends Error {
     status;
@@ -92,6 +108,7 @@ export class PrizedError extends Error {
     sandboxId;
     body;
     retryAfter;
+    exitCode;
     constructor(code, message, init = {}) {
         super(message || defaultMessage(code), init.cause === undefined ? undefined : { cause: init.cause });
         this.name = 'PrizedError';
@@ -101,6 +118,7 @@ export class PrizedError extends Error {
         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}`;
@@ -135,6 +153,30 @@ export class CommandTimeoutError extends PrizedError {
         return this.result.stderr;
     }
 }
+/**
+ * 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 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;
+    }
+}
 function stringField(record, key) {
     const value = record[key];
     return typeof value === 'string' && value !== '' ? value : null;
@@ -246,5 +288,10 @@ export function errorFromResponse(status, text, retryAfter, 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/esm/files.d.ts

@@ -11,7 +11,13 @@ export interface WriteOptions {
      */
     mode?: number;
 }
-/** The sandbox's file transfers take at most this long, retries included. */
+/**
+ * The sandbox's file transfers take at most this long, retries included:
+ * the edge's own limit on one transfer. An attempt that moves no bytes for
+ * timing.transferStallMs (2 minutes) is given up; a download, or a write's
+ * staged upload, is then sent again (as after a lost answer or a 502, 503 or
+ * 504) while time is left.
+ */
 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;
@@ -54,12 +60,22 @@ export declare class Files {
      * 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.
-     * Sent again only if it provably never arrived: a write whose answer 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).
+     * The bytes go up under a temporary name beside the file, sent again if
+     * need be (a lost answer, a 502, 503 or 504, 2 minutes with no bytes
+     * moving; 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. */
+    /**
+     * 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