@prized/sdk 0.1.0 → 0.1.2

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,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

package/dist/cjs/files.js

@@ -9,7 +9,13 @@ const http_js_1 = require("./http.js");
 const outcome_js_1 = require("./outcome.js");
 const shell_js_1 = require("./shell.js");
 const toolbox_js_1 = require("./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. 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.
+ */
 exports.FILE_TIMEOUT_MS = 10 * 60_000;
 function byteSize(data) {
     if (typeof data === 'string')
@@ -45,12 +51,16 @@ exports.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. */
@@ -159,6 +169,7 @@ class Files {
             retry: 'safe',
             read: 'bytes',
             timeoutMs: exports.FILE_TIMEOUT_MS,
+            stallMs: http_js_1.timing.transferStallMs,
             deadline: this.toolbox.config.now() + exports.FILE_TIMEOUT_MS,
             sandboxId: this.toolbox.sandboxId,
         });
@@ -170,9 +181,13 @@ 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).
      */
     async write(path, data, options = {}) {
         const sandboxId = this.toolbox.sandboxId;
@@ -184,14 +199,18 @@ class Files {
         const target = (0, shell_js_1.sandboxPath)(path);
         const plan = stagingFor(target);
         if (plan === null)
-            return this.send(target, data, size, target, (0, outcome_js_1.writeEffect)(target));
+            return this.send(target, data, size, target, (0, outcome_js_1.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 ((0, outcome_js_1.mayHaveActed)(error))
                     await this.discard(staging);
                 throw error;
@@ -217,7 +236,7 @@ class Files {
             return { path: clean, size };
         if (result.exitCode === exports.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, (0, outcome_js_1.writeEffect)(clean));
+            const info = await this.send(clean, data, size, clean, (0, outcome_js_1.writeEffect)(clean), 'exec');
             if (mode !== null)
                 await this.chmod(clean, mode);
             return info;
@@ -228,18 +247,23 @@ class Files {
         const denied = /Permission denied|Operation not permitted/.test(result.stderr);
         throw new errors_js_1.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 (0, http_js_1.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: exports.FILE_TIMEOUT_MS,
+            stallMs: http_js_1.timing.transferStallMs,
             deadline: this.toolbox.config.now() + exports.FILE_TIMEOUT_MS,
             sandboxId: this.toolbox.sandboxId,
         });

package/dist/cjs/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,13 @@ 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. The start of a background, streamed or long `exec` is
+     * sent again for as long, so an edge that restarts mid-start does not
+     * cost the command.
      */
     pollOutageMs?: number;
     /** Sleep seam (tests inject one that never really waits). */
@@ -48,13 +56,21 @@ export interface Config {
     sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
     now: () => number;
     random: () => number;
+    /**
+     * Whether an upload's body goes out as a stream the SDK feeds piece by
+     * piece, so a stalled one is seen (RequestSpec.stallMs): Node's own fetch
+     * only, which asks for each piece once the last has gone into the socket.
+     * Elsewhere (another runtime, a fetch you pass) the body goes as it is.
+     */
+    streamBodies: boolean;
 }
 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, and how long a start is sent again: long
+ * enough to ride out a dropped connection or an edge that restarts (about
+ * 70 s, the last time it crashed). 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 +79,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;
 /**
@@ -88,13 +107,20 @@ export declare function warmEdge(config: Config): Promise<void>;
  *   Retries network failures, 429/502/503/504, and everything `exec`
  *   retries (the edge's 500 control_plane_unavailable among them). A GET
  *   retries any 500 too (the API's `internal`).
- * - `exec`: a command, an upload or a remove: what the sandbox does
- *   meanwhile could be undone by a second copy. Retried only when it
+ * - `exec`: a command, an upload, a remove or a label-selected delete:
+ *   a second copy could affect later work. Retried only when it
  *   provably never arrived: a connection that never opened, or an answer
  *   saying so (the edge's rate limit, its lookup failing). A lost answer
  *   is never retried: it may already have run.
+ * - `staged`: a write's upload to a fresh name beside its target, which only
+ *   a command after it puts in place (files.ts). Retried as `safe` (a lost
+ *   answer, a timeout, 429/502/503/504) and `exec` both, a GET's 500 aside:
+ *   every copy writes the same bytes under the same name, which nothing else
+ *   writes, so a second one changes no file of the caller's. A 2xx whose body
+ *   broke off is not sent again: the bytes are there. Its error says whether
+ *   a copy may have reached the sandbox.
  */
-export type RetryMode = 'safe' | 'exec';
+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
@@ -123,6 +149,14 @@ export interface RequestSpec {
     sandboxId?: string | null;
     /** How to read a 2xx body. Default `json`. */
     read?: 'json' | 'bytes' | 'none';
+    /**
+     * A file transfer's no-progress bound: an attempt that moves no bytes
+     * either way for this long (a connection dropped without a reset) ends as
+     * a timeout, sent again by `retry`'s rules while `deadline` allows. An
+     * upload's sending is watched only where its body is streamed
+     * (Config.streamBodies); its answer always is.
+     */
+    stallMs?: number;
     /**
      * Told of every attempt that failed (no answer, an error answer, or a 2xx
      * that could not be read), before it is retried or thrown. A create or
@@ -137,6 +171,12 @@ export interface RequestSpec {
      * its error says so too.
      */
     effect?: Effect;
+    /**
+     * An earlier copy of this keyed request may have reached the sandbox (the
+     * background start, sent again through an outage), so its error says so
+     * too.
+     */
+    acted?: boolean;
 }
 export interface HttpResult {
     status: number;
@@ -199,6 +239,25 @@ export declare class Polls {
 }
 /** Delay before retry number `attempt` (0-based): exponential with jitter. */
 export declare function backoffMs(config: Config, attempt: number): number;
+/**
+ * How long a file transfer may move no bytes before the attempt is given up
+ * (sdk/retry-spec.json transferStallMs; the Python SDK's TRANSFER_STALL).
+ * The edge holds a request about 20 s at most before it reads the body (its
+ * admission queue, then waking a paused sandbox), and ends a body that brings
+ * nothing for 60 s itself: kept above that, a stalled copy is over at the
+ * edge before the next one goes to the same staged name, so the two never
+ * race. Once an upload's last byte is handed over, its answer is waited for
+ * that and a second more for every uploadAnswerBytesPerSecond it sent: what
+ * the socket's buffers, or a proxy that takes a whole body before it sends it
+ * on, still hold moves unseen, and must not read as a stall (the Python SDK's
+ * UPLOAD_ANSWER_RATE). Mutable for tests only.
+ */
+export declare const timing: {
+    transferStallMs: number;
+    uploadAnswerBytesPerSecond: number;
+};
+/** A streamed upload goes out this many bytes at a time. */
+export declare const UPLOAD_CHUNK: number;
 /**
  * What an error answer (not a 2xx: request() judges those) says about
  * whether the sandbox acted: `never` for the codes that prove the request