@prized/sdk 0.1.0 → 0.1.1

package/README.md

@@ -47,7 +47,9 @@ No runtime dependencies. ESM and CommonJS, with type declarations.
 Make an API key on the [API keys page](https://prized.dev/dashboard/workspace/api-keys)
 and put it in `PRIZED_API_KEY`, or pass it in. New to Prized?
 [Open Sandboxes](https://prized.dev/onboarding/sandboxes) signs you up (free
-credit, no card) and makes one.
+credit, no card) and makes one. Or your coding agent can sign you up itself
+with your email and a 6-digit code: have it follow
+[prized.dev/auth.md](https://prized.dev/auth.md).
 
 ```ts
 const sandbox = await Sandbox.create({ apiKey: 'dcp_…' });
@@ -64,13 +66,23 @@ client options:
 | Option | Default | |
 |---|---|---|
 | `apiKey` | `process.env.PRIZED_API_KEY` | |
-| `baseUrl` | `https://api.prized.dev` | The API origin. |
-| `edgeUrl` | the sandbox's own `toolboxBase` | Where commands and files go. |
+| `baseUrl` | `https://api.prized.dev` | The API origin: `https`, or plain `http` on `localhost`, `127.0.0.1` or `[::1]`. |
+| `edgeUrl` | the sandbox's own `toolboxBase` | Where commands and files go, by the same rule. Pass it for another deployment whose API names its command endpoint on another host. |
 | `fetch` | global `fetch` | Bring your own (for a proxy, custom agent, tests). |
 | `maxRetries` | `3` | See [Retries](#retries-and-timeouts). |
 | `requestTimeoutMs` | `60000` | Per API request. |
 | `pollIntervalMs` | `500` | The longest the SDK's own polling goes between checks of the sandbox (the first come sooner). It does not cover the request itself, or the time the API holds a create, pause or resume for you (up to 8 seconds). |
-| `pollOutageMs` | `120000` | How long a streamed or long `exec` keeps polling through a dropped connection (or a 5xx, or a rate limit) before it stops the command. `exec` takes it per call too. |
+| `pollOutageMs` | `120000` | How long a wait keeps polling through a dropped connection (or a 5xx, or a rate limit) before it gives up: a streamed or long `exec` then stops the command, a handle's `wait()` throws. `exec` and `wait()` take it per call too. |
+
+Your API key goes with every request, so a plain `http` URL to a host other
+than this machine is refused with `invalid_argument` before anything is sent,
+whatever `fetch` you pass. Without `edgeUrl`, a sandbox's `toolboxBase` is used
+only on the API's own host, on Prized's own hosts beside Prized's API, or on
+this machine beside a local API. Otherwise commands and files go to Prized's
+edge for Prized's API; for any other API they throw `edge_unknown`, so its key
+never reaches Prized's edge. Take `baseUrl`, `edgeUrl` and `fetch` only from
+configuration you trust: what they name gets your key, your commands and your
+files.
 
 A sandbox remembers the options it was made with: its methods need none.
 
@@ -212,6 +224,7 @@ r.stderr;      // string, kept separate
 r.exitCode;    // number
 r.durationMs;
 r.truncated;   // true if stdout or stderr hit the 4 MiB per-call cap
+r.truncatedReason; // why, when truncated: 'output_limit' or 'write_failed'
 
 await sandbox.exec(['git', 'commit', '-m', "it's done"]); // quoted for you
 ```
@@ -225,6 +238,14 @@ small; past 4 MiB the SDK reads it back from files in
 ends gets `exitCode` 128+n (a plain exec may give -1), as a background command
 does.
 
+`truncatedReason` says why a result is cut: `output_limit` for a stream
+that reached its cap, `write_failed` when the sandbox could not save a
+stream as the command printed it (most often a full disk), so it stops where
+the write failed. If the output can't be read back afterwards, the call
+throws `OutputReadError` (`code` `output_read_failed`): the command ran
+(`err.exitCode`), `err.reason` says what stopped the read, and the output
+stays at `err.stdoutPath` and `err.stderrPath` for an hour.
+
 ```ts
 const { stdout, exitCode } = await sandbox.exec('npm test', { timeoutMs: 180_000, fullOutput: true });
 ```
@@ -306,6 +327,13 @@ result.exitCode;
 await job.cleanup();  // remove its output files from the sandbox
 ```
 
+`wait()` rides out a dropped connection too: while its polls fail (no
+answer, a 5xx, a rate limit) it keeps polling for up to `pollOutageMs` (2
+minutes by default, on the call or the client; while the command runs,
+never past its `timeoutMs`) before it throws what they met. A refused key,
+or an answer that settles the run, throws at once. Either way the command
+keeps running and the handle stays good: call `wait()` again.
+
 A background command has no time limit unless you give `timeoutMs`
 (enforced to the second: the command gets SIGTERM, then SIGKILL five seconds
 later, and `wait()` throws `CommandTimeoutError`). Its output is kept under
@@ -321,9 +349,10 @@ sandbox's disk there, so redirect such output yourself.
 ## Files
 
 `sandbox.files` reads and writes the sandbox's disk. Paths are absolute or
-relative to `/home/prized/work`. Writes, reads, uploads and downloads must
-stay inside `/home/prized`, are at most 100 MiB each, and do not follow
-symbolic links. A write replaces the file whole, and a file it replaces keeps
+relative to `/home/prized/work`. Writes, reads, uploads and downloads are at
+most 100 MiB each, and their paths in the sandbox must stay inside
+`/home/prized` and not go through a symbolic link (`symlink_not_allowed`).
+A write replaces the file whole, and a file it replaces 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.
@@ -511,12 +540,14 @@ try {
 | `file_too_large` | 413 | Over the 100 MiB transfer limit. |
 | `idempotency_conflict` | 409 | The idempotency key was used for a different request. |
 | `sandbox_error` | | The sandbox failed while you waited; `reason` says why. |
-| `sandbox_deleted` | 410 | The sandbox was deleted before or while a command or file call ran; a command that was running stopped with it. `pause()` and `resume()` of a sandbox being deleted throw it too. Not retried. A wait that finds the sandbox deleted throws it too, with no status. |
+| `sandbox_deleted` | 410 | The sandbox was deleted before or while a command or file call ran; a command that was running stopped with it. `pause()` and `resume()` of a sandbox being deleted throw it too. Not retried. A wait that finds the sandbox deleted throws it too, with no status. When a `fullOutput` command ran and the sandbox went before its output was read back, `err.exitCode` is the command's exit code (null otherwise): it ran, so don't run it again blindly in a new sandbox. |
 | `command_timeout` | | A command ran past its own `timeoutMs` and was killed. Thrown as `CommandTimeoutError`; `err.result` has what it printed. |
+| `output_read_failed` | | A `fullOutput` command ran, but its output could not be read back. Thrown as `OutputReadError`: `err.exitCode` is the command's, `err.reason` the code of what stopped the read (also in `cause`), and the output stays at `err.stdoutPath` / `err.stderrPath` for an hour. The sandbox is not known to be gone (a deleted one throws `sandbox_deleted`); don't run the command again blindly. |
 | `timeout` | | A wait ran past its `timeoutMs`, or a call past its bound ([Retries](#retries-and-timeouts)). One that ended because a retry could not start in time says what the last attempt met (also in `cause`). |
 | `network_error` | | No answer: the API or the sandbox could not be reached, or the connection dropped. |
 | `bad_response` | 2xx | An answer the SDK could not read. For a command or file write it did happen, and the message says so. |
 | `missing_api_key` / `invalid_api_key` / `invalid_argument` | | Fix the call. `invalid_api_key`: the key has characters no key has (the docs' placeholder, a stray character); it is never quoted back. |
+| `edge_unknown` | | A `baseUrl` other than Prized's whose API named no command endpoint the SDK trusts (on the API's own host, or on this machine beside a local API): pass `edgeUrl`. The command or file call was not sent. |
 | `command_failed` | | A file helper (`list`, `remove`, `exists`) failed in the sandbox; `message` has its stderr. |
 
 ## Retries and timeouts
@@ -537,12 +568,17 @@ try {
   `keepAlive`, and 10 minutes for a file transfer. `Retry-After` is honoured
   up to a minute. A retry that could not start in time is not sent: the call
   throws `timeout`. A wait's last poll goes out just before its deadline.
-- A command, an upload (`files.write`, `files.upload`), a `files.remove` or
-  a `kill` is sent again only when it provably never arrived: the connection never
-  opened, or the answer says so (rate limited, the sandbox not ready). If an
-  answer is lost after it was delivered, the SDK throws
-  (`sandbox_unreachable`, `network_error`, `timeout`) rather than risk running a command
-  twice or overwriting what the sandbox wrote to the file since.
+- A command, a `files.remove` or a `kill` is sent again only when it
+  provably never arrived: the connection never opened, or the answer says so
+  (rate limited, the sandbox not ready). If an answer is lost after it was
+  delivered, the SDK throws (`sandbox_unreachable`, `network_error`,
+  `timeout`) rather than risk running a command twice.
+- A file write (`files.write`, `files.upload`) goes up under a temporary name
+  beside the file, which is sent again like a read (a lost answer, a 502, 503
+  or 504), every copy to the same name and none after the transfer's 10
+  minutes, so one that timed out is not sent again. One command that is never
+  sent again then puts it in place: if that command's answer is lost, the SDK
+  throws rather than risk overwriting what the sandbox wrote to the file since.
 - Did it run? When a command answered in one call (`exec` without
   `background`, `onStdout` or `onStderr`, and a `timeoutMs` other than 0 and
   at most 4 minutes), a file write or a `files.remove` fails without a plain refusal,
@@ -552,7 +588,10 @@ try {
   clear answer came back (a dropped connection, a timeout, or any other 5xx):
   it may or may not have run, and the message says how to check (read the
   file back, `files.exists()`). A 2xx came back that could not be read
-  (`bad_response`): it ran. A `kill` says the same of its signal
+  (`bad_response`): it ran. A write whose upload got no clear answer says the file was
+  not changed (its new bytes may have reached the sandbox under the
+  temporary name, which the SDK then removes): write it again. A `kill`
+  says the same of its signal
   (`status()` tells you whether the command is still running). A background
   command (or a streamed or long `exec`, which runs as one) whose start got
   no clear answer is stopped by the SDK, and the error says so, or, when the
@@ -563,6 +602,8 @@ try {
   poll's own error as its `cause`, and says whether the SDK stopped the
   command or it may still be running. An error that settles it (the
   sandbox deleted or not running, the run not found) is thrown as it came.
+  A handle's `wait()` whose polls fail for longer than `pollOutageMs` throws
+  the poll's own error; it stops nothing.
 - Deleting what a failed create or fork made (a few seconds) comes on top
   of `timeoutMs`.
 - `create`, `exec` and waits take an `AbortSignal` (`signal`). Aborting a

package/dist/cjs/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. */
@@ -95,11 +109,26 @@ export interface ExecOptions {
     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 +165,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/cjs/commands.js

@@ -70,22 +70,42 @@ 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.
  */
 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(http_js_1.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) {
@@ -109,7 +129,10 @@ 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(http_js_1.LAST_LOOK_MAX_MS, (this.end - now) / 2));
+        }
         const met = error.cause instanceof errors_js_1.PrizedError ? error.cause : null;
         if (!cut) {
             this.last = error;
@@ -278,17 +301,20 @@ 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 = (0, http_js_1.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);
@@ -296,7 +322,7 @@ class CommandHandle {
         let delay = POLL_MIN_MS;
         let finished = false;
         const polls = deadline === null ? null : new http_js_1.Polls(config, deadline);
-        const outage = new Outage(deadline === null ? outageMs : 0);
+        const outage = new Outage(outageMs, deadline);
         for (;;) {
             let report;
             const sentAt = config.now();
@@ -311,13 +337,15 @@ class CommandHandle {
                 polls?.answered();
             }
             catch (error) {
-                if (deadline !== null && error instanceof errors_js_1.PrizedError && error.code === 'timeout')
+                const now = config.now();
+                if (error instanceof errors_js_1.PrizedError && outage.ranOut(error, now, (0, http_js_1.cutByDeadline)(error))) {
                     throw this.waitTimeout(options.timeoutMs);
+                }
                 let failure = error;
                 if (error instanceof errors_js_1.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(), (0, http_js_1.cutByDeadline)(error), (tries) => (0, http_js_1.backoffMs)(config, tries));
+                    const step = outage.failed(error, sentAt, now, (0, http_js_1.cutByDeadline)(error), (tries) => (0, http_js_1.backoffMs)(config, tries));
                     if (step.pause !== null) {
                         await config.sleep(step.pause, options.signal);
                         continue;
@@ -329,8 +357,10 @@ 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/cjs/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/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommandTimeoutError = exports.PrizedError = exports.FREE_TIER_URL = exports.SIGN_UP_URL = exports.API_KEYS_URL = void 0;
+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;
@@ -8,15 +8,22 @@ exports.errorFromResponse = errorFromResponse;
 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; 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}.`,
+    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.',
@@ -27,6 +34,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 ${exports.API_KEYS_URL}.`,
@@ -83,13 +91,21 @@ 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.
  */
 class PrizedError extends Error {
     status;
@@ -98,6 +114,7 @@ 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';
@@ -107,6 +124,7 @@ 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}`;
@@ -143,6 +161,31 @@ class CommandTimeoutError extends PrizedError {
     }
 }
 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;
@@ -254,5 +297,10 @@ 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/cjs/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