@prized/sdk 0.1.0 → 0.1.1

package/dist/esm/commands.js

@@ -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) ||

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,12 @@ 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. 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;
@@ -54,12 +59,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; 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

package/dist/esm/files.js

@@ -4,7 +4,12 @@ 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 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')
@@ -40,12 +45,16 @@ export const EXIT_TARGET_NOT_REGULAR = 48;
 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. */
+/**
+ * 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: 'It was not sent again: write it again.',
+        check: 'Write it again.',
     };
 }
 /** For the command that puts the staged upload in place: a 2xx proves it ran, not how it ended. */
@@ -165,9 +174,13 @@ export 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; 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;
@@ -179,14 +192,18 @@ export class Files {
         const target = sandboxPath(path);
         const plan = stagingFor(target);
         if (plan === null)
-            return this.send(target, data, size, target, writeEffect(target));
+            return this.send(target, data, size, target, writeEffect(target), 'exec');
         const { clean, staging } = plan;
         try {
-            await this.send(staging, data, size, clean, stagedEffect(clean));
+            // 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;
@@ -212,7 +229,7 @@ export class Files {
             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));
+            const info = await this.send(clean, data, size, clean, writeEffect(clean), 'exec');
             if (mode !== null)
                 await this.chmod(clean, mode);
             return info;
@@ -223,16 +240,20 @@ export class Files {
         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. */
-    async send(path, data, size, target, effect) {
+    /**
+     * 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',
-            // Like a command: a resend after the answer was lost could overwrite
-            // what the sandbox wrote to the path since.
-            retry: 'exec',
+            retry,
             effect,
             timeoutMs: FILE_TIMEOUT_MS,
             deadline: this.toolbox.config.now() + FILE_TIMEOUT_MS,

package/dist/esm/http.d.ts

@@ -6,11 +6,16 @@ export declare const DEFAULT_EDGE_URL = "https://term.prized.dev";
 export interface ClientOptions {
     /** Your API key (`dcp_…`). Default: the `PRIZED_API_KEY` environment variable. */
     apiKey?: string;
-    /** The API origin. Default: `https://api.prized.dev`. */
+    /**
+     * 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. Default: the `toolboxBase` the API
-     * returns for each sandbox (today `https://term.prized.dev`).
+     * 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`. */
@@ -23,10 +28,11 @@ export interface ClientOptions {
      *  the request itself and the API's hold of a create, pause or resume. Default 500. */
     pollIntervalMs?: number;
     /**
-     * How long a streamed or long `exec` keeps polling while its polls fail
-     * (no answer, a 5xx, a rate limit), in ms, before it gives up and stops
-     * the command. Default 120 000. `0` gives up once one poll's retries run
-     * out. `exec` takes it per call too.
+     * 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). */
@@ -51,10 +57,10 @@ export interface Config {
 }
 export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
 /**
- * How long a streamed or long exec keeps polling while its polls fail
- * before it stops the command (pollOutageMs): long enough to ride out a
- * dropped connection or an edge that restarts. The Python SDK's
- * DEFAULT_POLL_OUTAGE.
+ * 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. */
@@ -63,7 +69,10 @@ 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); else the default edge.
+ * 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;
 /**
@@ -93,8 +102,15 @@ export declare function warmEdge(config: Config): Promise<void>;
  *   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';
+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