@promigence/sdk 0.1.0-beta.8 → 0.1.0-beta.9

package/dist/cjs/client.d.ts

@@ -420,7 +420,19 @@ export interface SnapshotBuild {
     /** `true` when the snapshot this build made has since been deleted. */
     snapshot_deleted?: boolean;
     tier_assigned?: string;
+    /**
+     * The most the build can cost, USD, said before it runs: `max_seconds` at `per_second_usd`. A build
+     * is billed per second for the time it runs; what it cost is `cost_usd` once it has ended.
+     */
     build_price?: number;
+    /** What one second of the build costs, USD: its tier's per-second rate. */
+    per_second_usd?: number;
+    /** The longest the build may run, in seconds: it is billed for at most this long. */
+    max_seconds?: number;
+    /** Once it has ended, the seconds it is billed for; 0 when it failed on our side. */
+    billable_seconds?: number;
+    /** Once it has ended, what it cost, USD; 0 when nothing was charged. */
+    cost_usd?: number;
     repo?: string;
     commit?: string;
     verification?: Record<string, unknown>;
@@ -847,7 +859,10 @@ export interface PricingView {
         gib_second_usd: number;
         preemptible_vcpu_second_usd: number;
         preemptible_gib_second_usd: number;
-        /** One snapshot build, charged once it verifies. */
+        /**
+         * The most one snapshot build of the default tier can cost (`limits.build_max_s` seconds at that
+         * tier's rate). A build is billed per second at its own tier's rate for the time it runs.
+         */
         build_usd: number;
         /** Per GiB of data out above the month's allowance; `null` when not priced. */
         egress_gb_usd: number | null;
@@ -872,6 +887,8 @@ export interface PricingView {
         max_egress_gb_month: number | null;
         /** Outbound mail ports open. */
         smtp: boolean;
+        /** The longest a snapshot build may run, in seconds: the most one build is billed for. */
+        build_max_s?: number;
     };
     /** The free credit a new account gets (an account's own: `GET /credits/offer`). */
     free_credit: {
@@ -1447,7 +1464,11 @@ export interface PromigenceClientOpts {
      * From the CLI: `promigence --request-timeout DUR` or `PROMIGENCE_REQUEST_TIMEOUT`.
      */
     requestTimeoutMs?: number;
-    /** Retries on 429/503 only (default 3). */
+    /**
+     * How many times a request is sent again (default 3): after a 429 or a 503, and after a 502 or
+     * 504 that is not the API's own answer when sending twice is harmless (a read, a delete, or a
+     * create with its idempotency key).
+     */
     maxRetries?: number;
     /** Backoff base when the server sends no `Retry-After` (default 250 ms). */
     retryBaseMs?: number;
@@ -1885,7 +1906,7 @@ interface RequestOpts {
     signal?: AbortSignal;
     /** Skip the Authorization header (unauthenticated routes). */
     anonymous?: boolean;
-    /** Called with the response headers of the attempt that answered (not of a retried 429/503). */
+    /** Called with the response headers of the attempt that answered (not of one that was retried). */
     onHeaders?: (headers: Headers) => void;
     /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
     headers?: Record<string, string>;
@@ -1960,8 +1981,10 @@ export declare class PromigenceClient {
      * rule `request()` applies, for the calls that cannot go through it (byte transfers, the
      * opening of an exec stream, the terminal handshake). Retried: a 429, and a 503 that says
      * nothing started — any 503 for a request safe to send twice, else only one carrying a
-     * `Retry-After` (every refusal at the door sets one) or a refusal code. At most `maxRetries`
-     * times, and never a `Retry-After` longer than MAX_RETRY_SLEEP_MS: that one is the caller's.
+     * `Retry-After` (every refusal at the door sets one) or a refusal code — and, for a request
+     * safe to send twice, a 502 or 504 that is not the API's own answer (it carries no error
+     * code). At most `maxRetries` times, and never a `Retry-After` longer than
+     * MAX_RETRY_SLEEP_MS: that one is the caller's.
      */
     private refusalBackoff;
     /** A long-poll request must outlive its own `wait_ms`; everything else keeps the default. */
@@ -1998,7 +2021,7 @@ export declare class PromigenceClient {
     }): Promise<StatusResponse>;
     /**
      * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
-     * shape on sale and its price, the build price, the limits, the free credit and the plan they
+     * shape on sale and its price (a snapshot build bills at its tier's), the limits, the free credit and the plan they
      * come from, read on every call from what billing charges. Needs a key: without one this throws
      * `AuthError` and sends nothing. The published list prices are on the pricing page.
      *

package/dist/cjs/client.js

@@ -870,7 +870,8 @@ class PromigenceClient {
     refusalBackoff(status, retryAfterMs, code, attempt, replayable, signal) {
         if (attempt >= this.maxRetries || signal?.aborted)
             return undefined;
-        if (status !== 429 && status !== 503)
+        const gateway = (status === 502 || status === 504) && replayable && code === undefined;
+        if (status !== 429 && status !== 503 && !gateway)
             return undefined;
         if ((retryAfterMs ?? 0) > MAX_RETRY_SLEEP_MS)
             return undefined;
@@ -993,12 +994,17 @@ class PromigenceClient {
                 throw new core_js_1.UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
             }
             const retryAfterMs = parseRetryAfter(headerOf(res, "retry-after"));
-            let retryable = (res.status === 429 || res.status === 503) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
+            const gateway = (res.status === 502 || res.status === 504) && replayable;
+            let retryable = (res.status === 429 || res.status === 503 || gateway) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
             let body;
             if (retryable && res.status === 503 && !replayable && retryAfterMs === undefined) {
                 body = await res.text().catch(() => "");
                 retryable = REFUSED_503_CODES.has(errorCodeOf(body) ?? "");
             }
+            if (retryable && gateway) {
+                body = await res.text().catch(() => "");
+                retryable = errorCodeOf(body) === undefined;
+            }
             if (retryable && attempt < this.maxRetries) {
                 const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
                 const jitter = Math.random();
@@ -1006,6 +1012,8 @@ class PromigenceClient {
                     ? retryAfterMs + jitter * Math.min(250, this.retryBaseMs)
                     : backoff * (0.5 + jitter * 0.5);
                 this.stats.retries++;
+                if (gateway && opts.method === "DELETE")
+                    resentDelete = true;
                 if (body === undefined)
                     try {
                         await res.text();

package/dist/cjs/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.8";
+export declare const VERSION = "0.1.0-beta.9";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
@@ -14,12 +14,14 @@ export declare const WAIT_TIMEOUT_MS = 100000;
  */
 export declare const IMAGE_BUILD_TIMEOUT_MS: number;
 /**
- * The list price of one new snapshot build this SDK was built with, in USD (charged once it
- * verifies; a dedupe or a join is free). Prices change: the live one is `client.pricing()`'s
- * `rates.build_usd` (this key's organization's), and a build's own arrives as `build_price` in
- * the `POST /snapshots` answer. This is only the fallback when the API cannot be asked.
+ * The most one new snapshot build of the default tier can cost at the list prices this SDK was
+ * built with, in USD: its time limit (an hour) at that tier's per-second rate. A build is billed per
+ * second for the time it runs; reusing or joining an identical build is free. Prices change: the
+ * live figure is `client.pricing()`'s `rates.build_usd` (this key's organization's), and a build's
+ * own arrives as `build_price` in the `POST /snapshots` answer. This is only the fallback when the
+ * API cannot be asked.
  */
-export declare const IMAGE_BUILD_LIST_PRICE = 1;
+export declare const IMAGE_BUILD_LIST_PRICE = 0.1656;
 /** Inline output budget for an exec before `truncated` + `_ref`. */
 export declare const MAX_OUTPUT_BYTES_DEFAULT: number;
 /** One request of a `files.put`. **Not a file-size limit** — `put` loops. */

package/dist/cjs/core.js

@@ -7,14 +7,14 @@ exports.fixBeyondMessage = fixBeyondMessage;
 exports.previewsOff = previewsOff;
 exports.exitForCode = exitForCode;
 const hint_js_1 = require("./hint.js");
-exports.VERSION = "0.1.0-beta.8";
+exports.VERSION = "0.1.0-beta.9";
 exports.DOCS_URL = "https://promigence.ai";
 exports.ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 exports.DEFAULT_API_URL = "https://api.promigence.ai/v1";
 exports.KEY_CONTACT = "support@promigence.ai";
 exports.WAIT_TIMEOUT_MS = 100_000;
 exports.IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
-exports.IMAGE_BUILD_LIST_PRICE = 1.0;
+exports.IMAGE_BUILD_LIST_PRICE = 0.1656;
 exports.MAX_OUTPUT_BYTES_DEFAULT = 64 * 1024;
 exports.FILE_PUT_CHUNK_BYTES = 16 * 1024 * 1024;
 const PREVIEWS_OFF = /^previews are not enabled on this deployment\.?$/i;

package/dist/cjs/github.d.ts

@@ -34,7 +34,7 @@ export interface GithubPending {
     state: string;
     message: string;
 }
-/** A snapshot that follows a branch: every push builds it again (at the build price). */
+/** A snapshot that follows a branch: every push builds it again (each build billed per second). */
 export interface GithubTrack {
     track_id: string;
     repo: string;

package/dist/cjs/gitlab.d.ts

@@ -37,7 +37,7 @@ export interface GitlabPending {
     expires_at: string;
     message: string;
 }
-/** A snapshot that follows a GitLab branch: each new commit builds it again (at the build price). */
+/** A snapshot that follows a GitLab branch: each new commit builds it again (each build billed per second). */
 export interface GitlabTrack {
     track_id: string;
     repo: string;

package/dist/cjs/models.gen.d.ts

@@ -346,16 +346,29 @@ export interface BuildJoined {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when the running build carries another. It was not applied;
-     * `warnings` says what to do once the build verifies.
+     * The alias that was asked for, when the build in progress was to carry another, or none.
+     * The build carries it now (`alias_applied: true`) and its snapshot is stored under it;
+     * `warnings` names the alias the build was to carry.
      */
     alias_requested?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -378,10 +391,20 @@ export interface BuildJoined {
      * Always true here.
      */
     joined: boolean;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -412,8 +435,8 @@ export interface BuildJoined {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
-     * is charged if the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -455,7 +478,8 @@ export interface BuildQueued {
     alias?: string | null;
     build_id: string;
     /**
-     * What the build costs, in USD, said before it runs.
+     * The most the build can cost, in USD, said before it runs: `max_seconds` at
+     * `per_second_usd`. It is billed per second for the time it runs.
      */
     build_price: number;
     commit: string;
@@ -469,10 +493,18 @@ export interface BuildQueued {
      * given, so a client can say which earlier request this repeats.
      */
     idempotent_replay_age_s?: number | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate.
+     */
+    per_second_usd?: number | null;
     repo: string;
     /**
      * What it is being built from. The `kind` field says which of the three forms it is.
@@ -511,12 +543,24 @@ export interface BuildView {
      * the snapshot is deleted: the name may belong to another snapshot by then.
      */
     alias?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -529,10 +573,20 @@ export interface BuildView {
      * RFC 3339.
      */
     finished_at?: string | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -563,8 +617,8 @@ export interface BuildView {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
-     * is charged if the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -2460,7 +2514,7 @@ export interface LedgerEntryView {
      */
     seconds: number;
     /**
-     * What was charged: a sandbox id or a build id.
+     * What was charged: a sandbox id or a build id; for credit, what it is for (e.g. "Credit from Promigence").
      */
     subject: string;
     tier: string;
@@ -3103,6 +3157,11 @@ export interface PricingFreeCredit {
  * The limits in force.
  */
 export interface PricingLimits {
+    /**
+     * The longest a snapshot build may run, in seconds, and so the most seconds one build is
+     * billed for.
+     */
+    build_max_s?: number | null;
     /**
      * A sandbox's timeout when its run names none, in seconds.
      */
@@ -3161,8 +3220,11 @@ export interface PricingPlan {
  */
 export interface PricingRates {
     /**
-     * One snapshot build, charged once it verifies. A build that fails `verify` stores nothing
-     * and is not charged; reusing an identical build is free.
+     * The most one snapshot build of the default tier can cost: `limits.build_max_s` seconds at
+     * that tier's per-second rate. A build is billed per second at its own tier's rate (`tiers`)
+     * for the time it runs, whether it is stored, its own `setup` or `verify` fails, or it runs to
+     * its time limit; a failure on our side, and reusing or joining an identical build, cost
+     * nothing.
      */
     build_usd: number;
     /**
@@ -5201,8 +5263,7 @@ export interface SnapshotCreate {
  */
 export type SnapshotCreated = BuildQueued | BuildJoined | SnapshotDeduped;
 /**
- * Inputs that are already built: the existing snapshot, and whether the alias that was asked
- * for could be applied to it.
+ * Inputs that are already built: the existing snapshot, named with the alias that was asked for.
  */
 export interface SnapshotDeduped {
     /**
@@ -5211,8 +5272,10 @@ export interface SnapshotDeduped {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when it differs from the snapshot's. An unnamed snapshot
-     * takes the name (`alias_applied: true`); a named one keeps its own and `warnings` says so.
+     * The alias that was asked for, when the snapshot did not hold it. The snapshot takes it
+     * (`alias_applied: true`) as a new build would: another snapshot of the project that had it
+     * keeps its row, without a name. A snapshot has one alias, so a name it had before gives
+     * way, and `warnings` says which.
      */
     alias_requested?: string | null;
     /**

package/dist/cjs/sandbox.d.ts

@@ -136,7 +136,7 @@ export interface SandboxCreateOpts extends SandboxOpts {
     /**
      * A container image instead of a snapshot — a tag (`python:3.12`, pinned to its digest by the
      * API) or `registry/name@sha256:<64 hex>`: the snapshot of this image is built on first use
-     * (a new build is charged your build price once it verifies, `client.pricing()`; pass
+     * (a new build is billed per second while it runs, at its tier's rate, `client.pricing()`; pass
      * `allowBuild: true` to allow it) and
      * reused after (same digest + same inputs → the same snapshot). A name with no tag or digest is
      * refused: it would pin whatever `:latest` is today. The fields below shape that snapshot and
@@ -156,17 +156,17 @@ export interface SandboxCreateOpts extends SandboxOpts {
     buildTimeoutMs?: number;
     /**
      * Let `Sandbox.create({ image })` build the image's snapshot when none exists yet. A new build
-     * costs `build_price` (your plan's, `client.pricing()`; charged once it verifies); reusing a snapshot already built
-     * is free. Without it, a create from an image is refused before anything is sent: whether the
+     * is billed per second while it runs, at most `build_price` (your plan's rates, `client.pricing()`);
+     * reusing a snapshot already built is free. Without it, a create from an image is refused before anything is sent: whether the
      * image's snapshot exists is only known once a build is submitted, and a submitted build cannot
      * be withdrawn. The other way to pay once and on purpose: `promigence snapshot create --image
      * REF --alias NAME`, then `Sandbox.create("NAME")`.
      */
     allowBuild?: boolean;
     /**
-     * Called with the `POST /snapshots` answer before any wait: `build_price`, and `deduped` or
-     * `joined` when nothing new is charged. Without it, a new build's price is reported as a
-     * process warning (stderr) before the build is waited for.
+     * Called with the `POST /snapshots` answer before any wait: `build_price` (the most the build can
+     * cost) and `per_second_usd`, and `deduped` or `joined` when nothing new is charged. Without it,
+     * a new build's price is reported as a process warning (stderr) before the build is waited for.
      */
     onBuild?: (build: SnapshotBuild) => void | Promise<void>;
     /**
@@ -198,9 +198,8 @@ export interface SandboxCreateOpts extends SandboxOpts {
  */
 export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
-     * The `POST /snapshots` answer, before any wait: `build_price` and whether it was `deduped`
-     * or `joined` (nothing new charged). An implicit build costs money, so a caller
-     * that prints prices prints this one too.
+     * The `POST /snapshots` answer, before any wait: `build_price` (the most it can cost) and
+     * whether it was `deduped` or `joined` (nothing new charged). An implicit build costs money, so a caller that prints prices prints this one too.
      */
     onBuild?: (build: SnapshotBuild) => void | Promise<void>;
     /** Ends the wait for a build at once; the build itself, once submitted, is not withdrawn. */
@@ -375,7 +374,7 @@ export declare class Sandbox {
     /**
      * Fork of 1 from a snapshot (`snap_<id>` | `<alias>` | `<alias>@<commit7>`), or from the
      * snapshot of an image: `Sandbox.create({ image: 'python:3.12', allowBuild: true })` builds it
-     * on first use (a new build at your build price, bounded by `buildTimeoutMs`, default 15 min) and reuses it
+     * on first use (a new build billed per second at its tier's rate, bounded by `buildTimeoutMs`, default 15 min) and reuses it
      * free after. An image needs `allowBuild: true` and a tag or digest; without either it is
      * refused before any request.
      *

package/dist/cjs/sandbox.js

@@ -75,12 +75,16 @@ function buildNotice(image) {
     return (b) => {
         if (buildIsFree(b))
             return;
-        const price = typeof b.build_price === "number" ? `build_price $${b.build_price.toFixed(2)}` : "charged your build price";
-        process.emitWarning(`building a snapshot of ${image}: ${price}, charged once it verifies (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
+        const price = typeof b.build_price === "number"
+            ? typeof b.per_second_usd === "number"
+                ? `billed per second while it builds ($${Number(b.per_second_usd.toPrecision(12))}/s), at most $${b.build_price.toFixed(2)}`
+                : `build_price $${b.build_price.toFixed(2)}, charged once it verifies`
+            : "billed at your plan's rates";
+        process.emitWarning(`building a snapshot of ${image}: ${price} (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
     };
 }
 function buildNotAllowed(image) {
-    return new core_js_1.InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is charged your build price once it verifies (\`promigence pricing\` shows it; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
+    return new core_js_1.InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is billed per second while it runs (\`promigence pricing\` shows the rates; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
         `\`promigence snapshot create --image ${(0, hint_js_1.hintArg)(image)} --alias NAME\`, and create from its name: Sandbox.create("NAME").`);
 }
 async function imageSnapshot(client, opts, hooks = {}) {

package/dist/client.d.ts

@@ -420,7 +420,19 @@ export interface SnapshotBuild {
     /** `true` when the snapshot this build made has since been deleted. */
     snapshot_deleted?: boolean;
     tier_assigned?: string;
+    /**
+     * The most the build can cost, USD, said before it runs: `max_seconds` at `per_second_usd`. A build
+     * is billed per second for the time it runs; what it cost is `cost_usd` once it has ended.
+     */
     build_price?: number;
+    /** What one second of the build costs, USD: its tier's per-second rate. */
+    per_second_usd?: number;
+    /** The longest the build may run, in seconds: it is billed for at most this long. */
+    max_seconds?: number;
+    /** Once it has ended, the seconds it is billed for; 0 when it failed on our side. */
+    billable_seconds?: number;
+    /** Once it has ended, what it cost, USD; 0 when nothing was charged. */
+    cost_usd?: number;
     repo?: string;
     commit?: string;
     verification?: Record<string, unknown>;
@@ -847,7 +859,10 @@ export interface PricingView {
         gib_second_usd: number;
         preemptible_vcpu_second_usd: number;
         preemptible_gib_second_usd: number;
-        /** One snapshot build, charged once it verifies. */
+        /**
+         * The most one snapshot build of the default tier can cost (`limits.build_max_s` seconds at that
+         * tier's rate). A build is billed per second at its own tier's rate for the time it runs.
+         */
         build_usd: number;
         /** Per GiB of data out above the month's allowance; `null` when not priced. */
         egress_gb_usd: number | null;
@@ -872,6 +887,8 @@ export interface PricingView {
         max_egress_gb_month: number | null;
         /** Outbound mail ports open. */
         smtp: boolean;
+        /** The longest a snapshot build may run, in seconds: the most one build is billed for. */
+        build_max_s?: number;
     };
     /** The free credit a new account gets (an account's own: `GET /credits/offer`). */
     free_credit: {
@@ -1447,7 +1464,11 @@ export interface PromigenceClientOpts {
      * From the CLI: `promigence --request-timeout DUR` or `PROMIGENCE_REQUEST_TIMEOUT`.
      */
     requestTimeoutMs?: number;
-    /** Retries on 429/503 only (default 3). */
+    /**
+     * How many times a request is sent again (default 3): after a 429 or a 503, and after a 502 or
+     * 504 that is not the API's own answer when sending twice is harmless (a read, a delete, or a
+     * create with its idempotency key).
+     */
     maxRetries?: number;
     /** Backoff base when the server sends no `Retry-After` (default 250 ms). */
     retryBaseMs?: number;
@@ -1885,7 +1906,7 @@ interface RequestOpts {
     signal?: AbortSignal;
     /** Skip the Authorization header (unauthenticated routes). */
     anonymous?: boolean;
-    /** Called with the response headers of the attempt that answered (not of a retried 429/503). */
+    /** Called with the response headers of the attempt that answered (not of one that was retried). */
     onHeaders?: (headers: Headers) => void;
     /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
     headers?: Record<string, string>;
@@ -1960,8 +1981,10 @@ export declare class PromigenceClient {
      * rule `request()` applies, for the calls that cannot go through it (byte transfers, the
      * opening of an exec stream, the terminal handshake). Retried: a 429, and a 503 that says
      * nothing started — any 503 for a request safe to send twice, else only one carrying a
-     * `Retry-After` (every refusal at the door sets one) or a refusal code. At most `maxRetries`
-     * times, and never a `Retry-After` longer than MAX_RETRY_SLEEP_MS: that one is the caller's.
+     * `Retry-After` (every refusal at the door sets one) or a refusal code — and, for a request
+     * safe to send twice, a 502 or 504 that is not the API's own answer (it carries no error
+     * code). At most `maxRetries` times, and never a `Retry-After` longer than
+     * MAX_RETRY_SLEEP_MS: that one is the caller's.
      */
     private refusalBackoff;
     /** A long-poll request must outlive its own `wait_ms`; everything else keeps the default. */
@@ -1998,7 +2021,7 @@ export declare class PromigenceClient {
     }): Promise<StatusResponse>;
     /**
      * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
-     * shape on sale and its price, the build price, the limits, the free credit and the plan they
+     * shape on sale and its price (a snapshot build bills at its tier's), the limits, the free credit and the plan they
      * come from, read on every call from what billing charges. Needs a key: without one this throws
      * `AuthError` and sends nothing. The published list prices are on the pricing page.
      *

package/dist/client.js

@@ -837,7 +837,8 @@ export class PromigenceClient {
     refusalBackoff(status, retryAfterMs, code, attempt, replayable, signal) {
         if (attempt >= this.maxRetries || signal?.aborted)
             return undefined;
-        if (status !== 429 && status !== 503)
+        const gateway = (status === 502 || status === 504) && replayable && code === undefined;
+        if (status !== 429 && status !== 503 && !gateway)
             return undefined;
         if ((retryAfterMs ?? 0) > MAX_RETRY_SLEEP_MS)
             return undefined;
@@ -960,12 +961,17 @@ export class PromigenceClient {
                 throw new UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
             }
             const retryAfterMs = parseRetryAfter(headerOf(res, "retry-after"));
-            let retryable = (res.status === 429 || res.status === 503) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
+            const gateway = (res.status === 502 || res.status === 504) && replayable;
+            let retryable = (res.status === 429 || res.status === 503 || gateway) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
             let body;
             if (retryable && res.status === 503 && !replayable && retryAfterMs === undefined) {
                 body = await res.text().catch(() => "");
                 retryable = REFUSED_503_CODES.has(errorCodeOf(body) ?? "");
             }
+            if (retryable && gateway) {
+                body = await res.text().catch(() => "");
+                retryable = errorCodeOf(body) === undefined;
+            }
             if (retryable && attempt < this.maxRetries) {
                 const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
                 const jitter = Math.random();
@@ -973,6 +979,8 @@ export class PromigenceClient {
                     ? retryAfterMs + jitter * Math.min(250, this.retryBaseMs)
                     : backoff * (0.5 + jitter * 0.5);
                 this.stats.retries++;
+                if (gateway && opts.method === "DELETE")
+                    resentDelete = true;
                 if (body === undefined)
                     try {
                         await res.text();

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.8";
+export declare const VERSION = "0.1.0-beta.9";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
@@ -14,12 +14,14 @@ export declare const WAIT_TIMEOUT_MS = 100000;
  */
 export declare const IMAGE_BUILD_TIMEOUT_MS: number;
 /**
- * The list price of one new snapshot build this SDK was built with, in USD (charged once it
- * verifies; a dedupe or a join is free). Prices change: the live one is `client.pricing()`'s
- * `rates.build_usd` (this key's organization's), and a build's own arrives as `build_price` in
- * the `POST /snapshots` answer. This is only the fallback when the API cannot be asked.
+ * The most one new snapshot build of the default tier can cost at the list prices this SDK was
+ * built with, in USD: its time limit (an hour) at that tier's per-second rate. A build is billed per
+ * second for the time it runs; reusing or joining an identical build is free. Prices change: the
+ * live figure is `client.pricing()`'s `rates.build_usd` (this key's organization's), and a build's
+ * own arrives as `build_price` in the `POST /snapshots` answer. This is only the fallback when the
+ * API cannot be asked.
  */
-export declare const IMAGE_BUILD_LIST_PRICE = 1;
+export declare const IMAGE_BUILD_LIST_PRICE = 0.1656;
 /** Inline output budget for an exec before `truncated` + `_ref`. */
 export declare const MAX_OUTPUT_BYTES_DEFAULT: number;
 /** One request of a `files.put`. **Not a file-size limit** — `put` loops. */

package/dist/core.js

@@ -1,12 +1,12 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.8";
+export const VERSION = "0.1.0-beta.9";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";
 export const KEY_CONTACT = "support@promigence.ai";
 export const WAIT_TIMEOUT_MS = 100_000;
 export const IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
-export const IMAGE_BUILD_LIST_PRICE = 1.0;
+export const IMAGE_BUILD_LIST_PRICE = 0.1656;
 export const MAX_OUTPUT_BYTES_DEFAULT = 64 * 1024;
 export const FILE_PUT_CHUNK_BYTES = 16 * 1024 * 1024;
 const PREVIEWS_OFF = /^previews are not enabled on this deployment\.?$/i;

package/dist/github.d.ts

@@ -34,7 +34,7 @@ export interface GithubPending {
     state: string;
     message: string;
 }
-/** A snapshot that follows a branch: every push builds it again (at the build price). */
+/** A snapshot that follows a branch: every push builds it again (each build billed per second). */
 export interface GithubTrack {
     track_id: string;
     repo: string;

package/dist/gitlab.d.ts

@@ -37,7 +37,7 @@ export interface GitlabPending {
     expires_at: string;
     message: string;
 }
-/** A snapshot that follows a GitLab branch: each new commit builds it again (at the build price). */
+/** A snapshot that follows a GitLab branch: each new commit builds it again (each build billed per second). */
 export interface GitlabTrack {
     track_id: string;
     repo: string;

package/dist/models.gen.d.ts

@@ -346,16 +346,29 @@ export interface BuildJoined {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when the running build carries another. It was not applied;
-     * `warnings` says what to do once the build verifies.
+     * The alias that was asked for, when the build in progress was to carry another, or none.
+     * The build carries it now (`alias_applied: true`) and its snapshot is stored under it;
+     * `warnings` names the alias the build was to carry.
      */
     alias_requested?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -378,10 +391,20 @@ export interface BuildJoined {
      * Always true here.
      */
     joined: boolean;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -412,8 +435,8 @@ export interface BuildJoined {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
-     * is charged if the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -455,7 +478,8 @@ export interface BuildQueued {
     alias?: string | null;
     build_id: string;
     /**
-     * What the build costs, in USD, said before it runs.
+     * The most the build can cost, in USD, said before it runs: `max_seconds` at
+     * `per_second_usd`. It is billed per second for the time it runs.
      */
     build_price: number;
     commit: string;
@@ -469,10 +493,18 @@ export interface BuildQueued {
      * given, so a client can say which earlier request this repeats.
      */
     idempotent_replay_age_s?: number | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate.
+     */
+    per_second_usd?: number | null;
     repo: string;
     /**
      * What it is being built from. The `kind` field says which of the three forms it is.
@@ -511,12 +543,24 @@ export interface BuildView {
      * the snapshot is deleted: the name may belong to another snapshot by then.
      */
     alias?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -529,10 +573,20 @@ export interface BuildView {
      * RFC 3339.
      */
     finished_at?: string | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -563,8 +617,8 @@ export interface BuildView {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
-     * is charged if the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -2460,7 +2514,7 @@ export interface LedgerEntryView {
      */
     seconds: number;
     /**
-     * What was charged: a sandbox id or a build id.
+     * What was charged: a sandbox id or a build id; for credit, what it is for (e.g. "Credit from Promigence").
      */
     subject: string;
     tier: string;
@@ -3103,6 +3157,11 @@ export interface PricingFreeCredit {
  * The limits in force.
  */
 export interface PricingLimits {
+    /**
+     * The longest a snapshot build may run, in seconds, and so the most seconds one build is
+     * billed for.
+     */
+    build_max_s?: number | null;
     /**
      * A sandbox's timeout when its run names none, in seconds.
      */
@@ -3161,8 +3220,11 @@ export interface PricingPlan {
  */
 export interface PricingRates {
     /**
-     * One snapshot build, charged once it verifies. A build that fails `verify` stores nothing
-     * and is not charged; reusing an identical build is free.
+     * The most one snapshot build of the default tier can cost: `limits.build_max_s` seconds at
+     * that tier's per-second rate. A build is billed per second at its own tier's rate (`tiers`)
+     * for the time it runs, whether it is stored, its own `setup` or `verify` fails, or it runs to
+     * its time limit; a failure on our side, and reusing or joining an identical build, cost
+     * nothing.
      */
     build_usd: number;
     /**
@@ -5201,8 +5263,7 @@ export interface SnapshotCreate {
  */
 export type SnapshotCreated = BuildQueued | BuildJoined | SnapshotDeduped;
 /**
- * Inputs that are already built: the existing snapshot, and whether the alias that was asked
- * for could be applied to it.
+ * Inputs that are already built: the existing snapshot, named with the alias that was asked for.
  */
 export interface SnapshotDeduped {
     /**
@@ -5211,8 +5272,10 @@ export interface SnapshotDeduped {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when it differs from the snapshot's. An unnamed snapshot
-     * takes the name (`alias_applied: true`); a named one keeps its own and `warnings` says so.
+     * The alias that was asked for, when the snapshot did not hold it. The snapshot takes it
+     * (`alias_applied: true`) as a new build would: another snapshot of the project that had it
+     * keeps its row, without a name. A snapshot has one alias, so a name it had before gives
+     * way, and `warnings` says which.
      */
     alias_requested?: string | null;
     /**

package/dist/sandbox.d.ts

@@ -136,7 +136,7 @@ export interface SandboxCreateOpts extends SandboxOpts {
     /**
      * A container image instead of a snapshot — a tag (`python:3.12`, pinned to its digest by the
      * API) or `registry/name@sha256:<64 hex>`: the snapshot of this image is built on first use
-     * (a new build is charged your build price once it verifies, `client.pricing()`; pass
+     * (a new build is billed per second while it runs, at its tier's rate, `client.pricing()`; pass
      * `allowBuild: true` to allow it) and
      * reused after (same digest + same inputs → the same snapshot). A name with no tag or digest is
      * refused: it would pin whatever `:latest` is today. The fields below shape that snapshot and
@@ -156,17 +156,17 @@ export interface SandboxCreateOpts extends SandboxOpts {
     buildTimeoutMs?: number;
     /**
      * Let `Sandbox.create({ image })` build the image's snapshot when none exists yet. A new build
-     * costs `build_price` (your plan's, `client.pricing()`; charged once it verifies); reusing a snapshot already built
-     * is free. Without it, a create from an image is refused before anything is sent: whether the
+     * is billed per second while it runs, at most `build_price` (your plan's rates, `client.pricing()`);
+     * reusing a snapshot already built is free. Without it, a create from an image is refused before anything is sent: whether the
      * image's snapshot exists is only known once a build is submitted, and a submitted build cannot
      * be withdrawn. The other way to pay once and on purpose: `promigence snapshot create --image
      * REF --alias NAME`, then `Sandbox.create("NAME")`.
      */
     allowBuild?: boolean;
     /**
-     * Called with the `POST /snapshots` answer before any wait: `build_price`, and `deduped` or
-     * `joined` when nothing new is charged. Without it, a new build's price is reported as a
-     * process warning (stderr) before the build is waited for.
+     * Called with the `POST /snapshots` answer before any wait: `build_price` (the most the build can
+     * cost) and `per_second_usd`, and `deduped` or `joined` when nothing new is charged. Without it,
+     * a new build's price is reported as a process warning (stderr) before the build is waited for.
      */
     onBuild?: (build: SnapshotBuild) => void | Promise<void>;
     /**
@@ -198,9 +198,8 @@ export interface SandboxCreateOpts extends SandboxOpts {
  */
 export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
-     * The `POST /snapshots` answer, before any wait: `build_price` and whether it was `deduped`
-     * or `joined` (nothing new charged). An implicit build costs money, so a caller
-     * that prints prices prints this one too.
+     * The `POST /snapshots` answer, before any wait: `build_price` (the most it can cost) and
+     * whether it was `deduped` or `joined` (nothing new charged). An implicit build costs money, so a caller that prints prices prints this one too.
      */
     onBuild?: (build: SnapshotBuild) => void | Promise<void>;
     /** Ends the wait for a build at once; the build itself, once submitted, is not withdrawn. */
@@ -375,7 +374,7 @@ export declare class Sandbox {
     /**
      * Fork of 1 from a snapshot (`snap_<id>` | `<alias>` | `<alias>@<commit7>`), or from the
      * snapshot of an image: `Sandbox.create({ image: 'python:3.12', allowBuild: true })` builds it
-     * on first use (a new build at your build price, bounded by `buildTimeoutMs`, default 15 min) and reuses it
+     * on first use (a new build billed per second at its tier's rate, bounded by `buildTimeoutMs`, default 15 min) and reuses it
      * free after. An image needs `allowBuild: true` and a tag or digest; without either it is
      * refused before any request.
      *

package/dist/sandbox.js

@@ -65,12 +65,16 @@ function buildNotice(image) {
     return (b) => {
         if (buildIsFree(b))
             return;
-        const price = typeof b.build_price === "number" ? `build_price $${b.build_price.toFixed(2)}` : "charged your build price";
-        process.emitWarning(`building a snapshot of ${image}: ${price}, charged once it verifies (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
+        const price = typeof b.build_price === "number"
+            ? typeof b.per_second_usd === "number"
+                ? `billed per second while it builds ($${Number(b.per_second_usd.toPrecision(12))}/s), at most $${b.build_price.toFixed(2)}`
+                : `build_price $${b.build_price.toFixed(2)}, charged once it verifies`
+            : "billed at your plan's rates";
+        process.emitWarning(`building a snapshot of ${image}: ${price} (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
     };
 }
 function buildNotAllowed(image) {
-    return new InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is charged your build price once it verifies (\`promigence pricing\` shows it; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
+    return new InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is billed per second while it runs (\`promigence pricing\` shows the rates; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
         `\`promigence snapshot create --image ${hintArg(image)} --alias NAME\`, and create from its name: Sandbox.create("NAME").`);
 }
 export async function imageSnapshot(client, opts, hooks = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0-beta.9",
   "description": "The fastest sandboxes for AI agents and code. The Promigence TypeScript SDK: snapshot an environment once, fork it as often as you need, run commands in every copy. A simple Sandbox class and the full PromigenceClient, with zero runtime dependencies.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",