@promigence/sdk 0.1.0-beta.16 → 0.1.0-beta.17

package/dist/cjs/context.js

@@ -594,6 +594,11 @@ function packContext(dir, opts = {}) {
     const c = collect(dir, opts);
     for (const n of c.notes)
         opts.onNote?.(n);
+    const files = new Set(c.entries.filter((e) => e.kind !== "dir").map((e) => e.rel));
+    const unknown = [...new Set((opts.allowSecretFiles ?? []).map(insidePath))].filter((p) => !files.has(p));
+    if (unknown.length > 0) {
+        throw new core_js_1.InvalidArgumentError(`allowSecretFiles ${unknown.join(", ")}: no such file in this upload`, 'Name each file as listContext names it (its path inside the context sent), e.g. { allowSecretFiles: ["certs/test.pem"] }.');
+    }
     if (c.bytes > max) {
         const ig = c.ignore?.file;
         throw new core_js_1.InvalidArgumentError(`the build context is over ${max} bytes${ig ? ` even without what its ${ig} excludes` : ""}`, `${ig ? `Exclude more in ${ig}` : "Add a .dockerignore"}, point --context at a smaller directory, or pass a git URL pinned to a full 40-character sha.`);

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.16";
+export declare const VERSION = "0.1.0-beta.17";
 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";
@@ -229,6 +229,20 @@ export declare class TimeoutError extends PromigenceError {
 export declare class ServiceRestartError extends PromigenceError {
     constructor(message: string, fix: string);
 }
+/**
+ * The connection dropped while a command was running (`sandboxes.exec`, `execStream`,
+ * `commands.run`), and the command could not be picked up again: no client came back for it in
+ * time, or the service no longer keeps it. The sandbox keeps running. `retryable` is `false`: the
+ * command may have done part of its work before it stopped, so run it again only if that is safe.
+ * exit 3
+ */
+export declare class ExecLostError extends PromigenceError {
+    /** The sandbox the command ran in. */
+    readonly sandboxId: string | undefined;
+    constructor(message: string, ids?: {
+        sandboxId?: string;
+    }, lost?: "gone" | "not_reattached" | "unreachable");
+}
 /** An API error with no more specific class (5xx, unknown code). exit from the table. */
 export declare class ApiError extends PromigenceError {
 }
@@ -266,6 +280,12 @@ export interface CommandResult {
     truncated?: boolean;
     /** `exec_id`, for `promigence exec output <exec_id>` / `GET /sandboxes/:id/execs/:exec_id`. */
     execId?: string;
+    /**
+     * `true` when the command was killed at its own time bound (see `timeoutMs`), `false` for any
+     * other exit. With `throwOnExit: false` this is how a result tells a timeout from any other
+     * exit 137, such as an out-of-memory kill or a `kill -9`. Set on every result the SDK returns.
+     */
+    timedOut?: boolean;
 }
 export interface CommandRunOpts {
     cwd?: string;
@@ -277,7 +297,10 @@ export interface CommandRunOpts {
      * (or the default 15 minutes).
      */
     timeoutMs?: number;
-    /** Throw `CommandExitError` on non-zero exit (default true). */
+    /**
+     * Throw `CommandExitError` on non-zero exit (default true). With `false`, a foreground command's
+     * result comes back instead, and its `timedOut` says whether it was killed at its time bound.
+     */
     throwOnExit?: boolean;
     /** Inline output budget; `truncated` beyond it (default 64 KiB). */
     maxOutputBytes?: number;

package/dist/cjs/core.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXIT_BY_CODE = exports.NotReleasedError = exports.ApiError = exports.ServiceRestartError = exports.TimeoutError = exports.RateLimitError = exports.UnreachableError = exports.NotFoundError = exports.AuthError = exports.NotVerifiedError = exports.SpendCapError = exports.CommandExitError = exports.EnvFailedError = exports.SandboxEndedError = exports.SANDBOX_ENDED_FIX = exports.PreviewsUnavailableError = exports.UnsupportedError = exports.InvalidArgumentError = exports.PromigenceError = exports.PREVIEWS_UNAVAILABLE = exports.FILE_PUT_CHUNK_BYTES = exports.MAX_OUTPUT_BYTES_DEFAULT = exports.IMAGE_BUILD_LIST_PRICE = exports.IMAGE_BUILD_TIMEOUT_MS = exports.WAIT_TIMEOUT_MS = exports.KEY_CONTACT = exports.DEFAULT_API_URL = exports.ERRORS_DOCS_URL = exports.DOCS_URL = exports.VERSION = void 0;
+exports.EXIT_BY_CODE = exports.NotReleasedError = exports.ApiError = exports.ExecLostError = exports.ServiceRestartError = exports.TimeoutError = exports.RateLimitError = exports.UnreachableError = exports.NotFoundError = exports.AuthError = exports.NotVerifiedError = exports.SpendCapError = exports.CommandExitError = exports.EnvFailedError = exports.SandboxEndedError = exports.SANDBOX_ENDED_FIX = exports.PreviewsUnavailableError = exports.UnsupportedError = exports.InvalidArgumentError = exports.PromigenceError = exports.PREVIEWS_UNAVAILABLE = exports.FILE_PUT_CHUNK_BYTES = exports.MAX_OUTPUT_BYTES_DEFAULT = exports.IMAGE_BUILD_LIST_PRICE = exports.IMAGE_BUILD_TIMEOUT_MS = exports.WAIT_TIMEOUT_MS = exports.KEY_CONTACT = exports.DEFAULT_API_URL = exports.ERRORS_DOCS_URL = exports.DOCS_URL = exports.VERSION = void 0;
 exports.errorsDocsFor = errorsDocsFor;
 exports.previewsFix = previewsFix;
 exports.withPreviewsFix = withPreviewsFix;
@@ -9,7 +9,7 @@ exports.previewsOff = previewsOff;
 exports.sandboxEndedIn = sandboxEndedIn;
 exports.exitForCode = exitForCode;
 const hint_js_1 = require("./hint.js");
-exports.VERSION = "0.1.0-beta.16";
+exports.VERSION = "0.1.0-beta.17";
 exports.DOCS_URL = "https://promigence.ai";
 exports.ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 function errorsDocsFor(code) {
@@ -118,9 +118,14 @@ class PreviewsUnavailableError extends InvalidArgumentError {
 }
 exports.PreviewsUnavailableError = PreviewsUnavailableError;
 const SANDBOX_ENDED = /^sandbox (\S+) has ended \(`([a-z_]+)`\)/;
+const SANDBOX_EXPIRED = /^sandbox (\S+) reached its timeout and ended\b/;
 function sandboxEndedIn(message) {
-    const m = SANDBOX_ENDED.exec(message.trim());
-    return m ? { sandboxId: m[1], state: m[2] } : undefined;
+    const text = message.trim();
+    const m = SANDBOX_ENDED.exec(text);
+    if (m)
+        return { sandboxId: m[1], state: m[2] };
+    const x = SANDBOX_EXPIRED.exec(text);
+    return x ? { sandboxId: x[1], state: "ended" } : undefined;
 }
 exports.SANDBOX_ENDED_FIX = "Start a new sandbox: Sandbox.create(). This one's getInfo() says how it ended (`outcome`).";
 class SandboxEndedError extends InvalidArgumentError {
@@ -243,6 +248,21 @@ class ServiceRestartError extends PromigenceError {
     }
 }
 exports.ServiceRestartError = ServiceRestartError;
+const EXEC_LOST_FIX = "The sandbox is still running; the command was stopped, maybe after part of its work: run it again if that is safe. " +
+    "Billed unless the drop was ours: then email support@promigence.ai with the sandbox id.";
+class ExecLostError extends PromigenceError {
+    sandboxId;
+    lost;
+    constructor(message, ids = {}, lost = "gone") {
+        super({
+            code: "exec_lost", message, fix: EXEC_LOST_FIX, docs: `${exports.ERRORS_DOCS_URL}#exec_lost`,
+            exitCode: 3, category: "env", retryable: false,
+        });
+        this.sandboxId = ids.sandboxId;
+        this.lost = lost;
+    }
+}
+exports.ExecLostError = ExecLostError;
 class ApiError extends PromigenceError {
 }
 exports.ApiError = ApiError;
@@ -263,6 +283,7 @@ exports.EXIT_BY_CODE = {
     not_connected: 7,
     service_restart: 3,
     digest_mismatch: 4,
+    exec_lost: 3,
     fork_failed: 3, start_timeout: 3, readiness_failed: 3, verify_too_slow: 3,
     verify_each_failed: 3, toolchain_mismatch: 3, sandbox_unresponsive: 3, oom_within_tier: 3,
     disk_full_within_tier: 3, sandbox_interrupted: 3, integrity_mismatch: 3, egress_unavailable: 3,

package/dist/cjs/handles.js

@@ -114,9 +114,10 @@ class CommandHandle {
             stderr: this.stderr,
             truncated: Boolean(this.record.truncated),
             execId: this.pid,
+            timedOut: (0, command_errors_js_1.exitTimedOut)(this.record.exit, this.opts.timeoutMs),
         };
         if (result.exitCode !== 0) {
-            if ((0, command_errors_js_1.exitTimedOut)(this.record.exit, this.opts.timeoutMs))
+            if (result.timedOut)
                 throw new command_errors_js_1.CommandTimeoutError(result, this.opts.timeoutMs);
             throw new core_js_1.CommandExitError(result);
         }

package/dist/cjs/http2.js

@@ -41,6 +41,7 @@ const FETCH_AT_LOAD = globalThis.fetch;
 const PROXY_VARS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"];
 const OFF = new Set(["0", "false", "off", "no"]);
 const NOT_IN_H2 = new Set(["connection", "keep-alive", "proxy-connection", "transfer-encoding", "upgrade", "host", "te"]);
+const ACCEPT_ENCODING = "br, gzip";
 function http2Allowed(opt, env = process.env) {
     try {
         const envFlag = env["PROMIGENCE_HTTP2"]?.trim().toLowerCase();
@@ -1100,6 +1101,8 @@ function exchange(pool, entry, target, init, deadline) {
             if (!NOT_IN_H2.has(name))
                 headers[name] = init.headers[k];
         }
+        if (headers["accept-encoding"] === undefined)
+            headers["accept-encoding"] = ACCEPT_ENCODING;
         headers[http2.sensitiveHeaders] = ["authorization"];
         const body = init.body === undefined ? undefined : Buffer.from(init.body, "utf8");
         if (body !== undefined)
@@ -1663,6 +1666,8 @@ class TransportThread {
             if (!NOT_IN_H2.has(name))
                 headers[name] = init.headers[k];
         }
+        if (headers["accept-encoding"] === undefined)
+            headers["accept-encoding"] = ACCEPT_ENCODING;
         if (init.body !== undefined)
             headers["content-length"] = Buffer.byteLength(init.body, "utf8");
         const id = this.nextId++;

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

@@ -358,7 +358,9 @@ export interface BillingCredits {
      */
     balance_usd: number;
     /**
-     * Available credits cannot start new work.
+     * Available credits cannot pay for new work. That stops new work only where credits pay for
+     * it (`model` `credits`, or the trial); a `postpaid` organization's new work is billed after
+     * use.
      */
     exhausted: boolean;
     /**
@@ -969,6 +971,24 @@ export interface CaptureView {
      */
     snapshot_id: string;
 }
+/**
+ * What applies to a failed run's sandboxes when the run does not say (`capture`).
+ */
+export interface CapturesEffective {
+    /**
+     * Which choice decided it: `project`, `org`, or `default` (neither chose, so the default
+     * applies).
+     */
+    from: CapturesFrom;
+    /**
+     * Whether a failed sandbox is kept so you can reopen it where it broke.
+     */
+    kept: boolean;
+}
+/**
+ * Which choice decides whether a failed run's sandboxes are kept, when the run does not say.
+ */
+export type CapturesFrom = "project" | "org" | "default";
 /**
  * The card on file, enough to recognise it.
  */
@@ -1508,6 +1528,45 @@ export interface ErrorBody {
  * Every error code the API returns. `category` decides whether the failure is billed: `env` is ours (not billed before hand-over; after it, the time since the sandbox's last snapshot is credited back, up to 24 hours, when our side shows the cause), `task` is your command and is billed. The full table is `x-promigence-error-codes` at the document root.
  */
 export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "stopped_by_support" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credits_exhausted" | "credit_unclaimed" | "setup_required" | "card_required" | "billing_unavailable" | "purchase_limit" | "card_needed" | "auto_reload_unavailable" | "purchases_blocked" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "billing_hold" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired" | "account_blocked";
+/**
+ * `POST /v1/sandboxes/{id}/execs/attach`: pick up a command whose connection dropped, by the key
+ * it was started with (the `Promigence-Exec-Key` header).
+ */
+export interface ExecAttach {
+    /**
+     * The key the command was started with.
+     */
+    key: string;
+    /**
+     * A stream only: the same for standard error.
+     */
+    stderr_offset?: number | null;
+    /**
+     * A stream only: how many bytes of standard output you already have; you are sent what
+     * follows. Default 0.
+     */
+    stdout_offset?: number | null;
+}
+/**
+ * `POST /v1/sandboxes/{id}/execs/cancel`: stop a command started with a key, now.
+ */
+export interface ExecCancel {
+    /**
+     * The key the command was started with.
+     */
+    key: string;
+}
+/**
+ * `POST /v1/sandboxes/{id}/execs/cancel`.
+ */
+export interface ExecCancelled {
+    /**
+     * True when the command was still running and is being stopped; false when it had already
+     * ended, which is not a failure.
+     */
+    cancelled: boolean;
+    sandbox_id: string;
+}
 /**
  * `POST /v1/sandboxes/{id}/execs`, and the `exec` of `POST /v1/runs`: one command. `argv` (a
  * non-empty list) or `sh` (a shell line) is required.
@@ -1614,8 +1673,9 @@ export interface ExecResult {
      */
     oom_killed?: boolean;
     /**
-     * Why the command ended without an exit code: `timeout`, `out_of_memory` or `signal`.
-     * Absent when it exited on its own.
+     * Why the command ended without an exit code: `timeout`, `out_of_memory`, `signal`, or
+     * `not_reattached` (it was started with a `Promigence-Exec-Key`, its connection dropped, and
+     * nobody picked it up again in time, so it was stopped). Absent when it exited on its own.
      */
     reason?: string | null;
     sandbox_id: string;
@@ -1796,7 +1856,8 @@ export interface Failure {
 }
 export type FailureCategory = "env" | "snapshot" | "task" | "cap" | "grader" | "preempt" | "other";
 /**
- * `POST /v1/sandboxes/{id}/files/archive`: pack a path into a `.tar.gz` inside the sandbox.
+ * `POST /v1/sandboxes/{id}/files/archive`: pack a path into a `.tar.gz` inside the sandbox. A path
+ * is absolute, or relative to the sandbox's working directory.
  */
 export interface FileArchive {
     /**
@@ -1804,13 +1865,15 @@ export interface FileArchive {
      */
     exclude?: Array<string>;
     /**
-     * Where the archive is written (absolute). Default: beside the source.
+     * Where the archive is written: absolute, or relative to the sandbox's working directory.
+     * Default: beside the source.
      */
     out?: string | null;
     path: string;
 }
 /**
- * `POST /v1/sandboxes/{id}/files/chmod`: at least one of `mode`, `uid`, `gid`.
+ * `POST /v1/sandboxes/{id}/files/chmod`: at least one of `mode`, `uid`, `gid`. The path is absolute,
+ * or relative to the sandbox's working directory.
  */
 export interface FileChmod {
     gid?: number | null;
@@ -1820,7 +1883,8 @@ export interface FileChmod {
     uid?: number | null;
 }
 /**
- * `POST /v1/sandboxes/{id}/files/copy`.
+ * `POST /v1/sandboxes/{id}/files/copy`. A path is absolute, or relative to the sandbox's working
+ * directory.
  */
 export interface FileCopy {
     from: string;
@@ -1829,7 +1893,8 @@ export interface FileCopy {
     to: string;
 }
 /**
- * `DELETE /v1/sandboxes/{id}/files`: a path, and `recursive` for a directory with something in it.
+ * `DELETE /v1/sandboxes/{id}/files`: a path (absolute, or relative to the sandbox's working
+ * directory), and `recursive` for a directory with something in it.
  */
 export interface FileDeleteRequest {
     path: string;
@@ -1850,7 +1915,8 @@ export interface FileDeleted {
     sandbox_id: string;
 }
 /**
- * `POST /v1/sandboxes/{id}/files/extract`.
+ * `POST /v1/sandboxes/{id}/files/extract`. A path is absolute, or relative to the sandbox's
+ * working directory.
  */
 export interface FileExtract {
     archive: string;
@@ -1890,7 +1956,7 @@ export interface FileListRequest {
      */
     limit?: number | null;
     /**
-     * The directory (absolute). Default: `/`.
+     * The directory: absolute, or relative to the sandbox's working directory. Default: `/`.
      */
     path?: string | null;
     /**
@@ -1914,7 +1980,8 @@ export interface FileListing {
     truncated: boolean;
 }
 /**
- * `POST /v1/sandboxes/{id}/files/mkdir`. Paths are absolute.
+ * `POST /v1/sandboxes/{id}/files/mkdir`. A path is absolute, or relative to the sandbox's working
+ * directory (where its commands start).
  */
 export interface FileMkdir {
     mode?: FileMode | null;
@@ -1929,7 +1996,8 @@ export interface FileMkdir {
  */
 export type FileMode = number | string;
 /**
- * `POST /v1/sandboxes/{id}/files/move`.
+ * `POST /v1/sandboxes/{id}/files/move`. A path is absolute, or relative to the sandbox's working
+ * directory.
  */
 export interface FileMove {
     from: string;
@@ -1937,8 +2005,8 @@ export interface FileMove {
     to: string;
 }
 /**
- * `POST /v1/sandboxes/{id}/files/read` and `POST /v1/sandboxes/{id}/files/stat`: one path,
- * absolute, inside the sandbox.
+ * `POST /v1/sandboxes/{id}/files/read` and `POST /v1/sandboxes/{id}/files/stat`: one path inside
+ * the sandbox, absolute or relative to its working directory (where its commands start).
  */
 export interface FilePathRequest {
     path: string;
@@ -1964,7 +2032,8 @@ export interface FileSearchRequest {
      */
     limit?: number | null;
     /**
-     * The directory to search (absolute). Default: `/`.
+     * The directory to search: absolute, or relative to the sandbox's working directory.
+     * Default: `/`.
      */
     path?: string | null;
     /**
@@ -2958,6 +3027,11 @@ export interface Me {
      */
     spend?: number | null;
     spend_detail?: SpendDetail | null;
+    /**
+     * What the organisation stores now, against `limits.max_storage_gb` and
+     * `limits.max_capture_storage_gb`. Absent from a server before it.
+     */
+    storage?: MeStorage | null;
     /**
      * The organisation's trial credit. Absent for a key that may not see the organisation's
      * money: only an owner's key of the default project does.
@@ -2982,6 +3056,11 @@ export interface MeConcurrency {
  * The limits in force for an organisation.
  */
 export interface MeLimits {
+    /**
+     * The storage saved failures may use, in GB: when a new one would pass it, the oldest are
+     * removed to make room; `null` for no limit.
+     */
+    max_capture_storage_gb?: number | null;
     /**
      * Sandboxes that may be live at once.
      */
@@ -2990,6 +3069,10 @@ export interface MeLimits {
      * Sandboxes that may be starting at once.
      */
     max_inflight: number;
+    /**
+     * Paused sandboxes that may be kept; `null` for no limit.
+     */
+    max_paused?: number | null;
     /**
      * The largest sandbox shape, in vCPU; `null` for no limit.
      */
@@ -2998,6 +3081,41 @@ export interface MeLimits {
      * The longest a sandbox may live, in seconds; `null` for no limit.
      */
     max_session_s?: number | null;
+    /**
+     * Snapshots that may be kept; `null` for no limit.
+     */
+    max_snapshots?: number | null;
+    /**
+     * Everything stored together, in GB: snapshots, paused sandboxes and saved failures; `null`
+     * for no limit.
+     */
+    max_storage_gb?: number | null;
+}
+/**
+ * What an organisation stores now (`GET /v1/me` `storage`).
+ */
+export interface MeStorage {
+    /**
+     * Saved failures kept now.
+     */
+    captures: number;
+    /**
+     * Of that, what saved failures use, in bytes (what `limits.max_capture_storage_gb` holds).
+     */
+    captures_bytes: number;
+    /**
+     * Paused sandboxes kept now.
+     */
+    paused: number;
+    /**
+     * Snapshots kept now.
+     */
+    snapshots: number;
+    /**
+     * Everything stored together, in bytes: snapshots, paused sandboxes and saved failures (what
+     * `limits.max_storage_gb` holds; a GB there is 2^30 bytes).
+     */
+    used_bytes: number;
 }
 /**
  * `GET /v1/orgs/{org_id}/members`.
@@ -3229,8 +3347,9 @@ export interface OrgList {
 export interface OrgPatch {
     /**
      * Keep a failed sandbox so it can be reopened where it broke, when a run does not say
-     * (`capture`): `true` or `false`; `null` = the next level's setting. Set by an owner, on its
-     * own (no other field in the same request).
+     * (`capture`): `true` or `false`; `null` = not chosen, so the default applies: not kept unless
+     * the organization or project chose to keep them. A project may choose its own. Set by an
+     * owner, on its own (no other field in the same request).
      */
     failure_captures?: boolean | null;
     /**
@@ -3243,6 +3362,13 @@ export interface OrgPatch {
      * owner.
      */
     output_retention_days?: number | null;
+    /**
+     * The length of new preview URLs when a request does not say: `short` or `long` (a longer,
+     * harder-to-guess URL, for apps with sensitive data); `null` = the default, `short`. A
+     * project may name its own. Set by an owner, on its own (no other field in the same
+     * request). Custom domains are coming soon.
+     */
+    preview_link_length?: PreviewLinkLength | null;
 }
 /**
  * One organization you belong to. Billing, members and credits belong to it.
@@ -3261,10 +3387,18 @@ export interface OrgView {
      */
     default: boolean;
     /**
-     * Whether a failed sandbox is kept so you can reopen it where it broke, when a run does not
-     * say (`capture`); `null` = the default. A project may name its own.
+     * This organization's choice: whether a failed sandbox is kept so you can reopen it where it
+     * broke, when a run does not say (`capture`); `null` = not chosen, so the default applies:
+     * not kept unless the organization or project chose to keep them. A project may choose its
+     * own. What applies is `failure_captures_effective`.
      */
     failure_captures?: boolean | null;
+    /**
+     * What applies to a failed run of this organization when neither the run (`capture`) nor
+     * its project says: kept or not, and which choice decided it. A run's own `capture` is
+     * followed either way.
+     */
+    failure_captures_effective?: CapturesEffective | null;
     members: number;
     name: string;
     org_id: string;
@@ -3273,6 +3407,11 @@ export interface OrgView {
      * name its own.
      */
     output_retention_days?: number | null;
+    /**
+     * The length of new preview URLs when a request does not say (`length`): `short` or `long`;
+     * `null` = the default, `short`. A project may name its own.
+     */
+    preview_link_length?: PreviewLinkLength | null;
     projects: number;
     /**
      * Your role in it: `owner` or `member`.
@@ -3543,6 +3682,12 @@ export interface Port {
      * need this form.
      */
     host_url_label?: string | null;
+    /**
+     * `short` (`https://brave-otter-48213.<domain>/`) or `long` (a longer, harder-to-guess
+     * URL). Which one a new URL gets: the request's `length`, else its project's setting, else
+     * its organization's, else `short`.
+     */
+    length?: PreviewLinkLength | null;
     /**
      * The port inside the sandbox.
      */
@@ -3569,6 +3714,12 @@ export interface PortList {
  * `POST /v1/sandboxes/{id}/ports`.
  */
 export interface PortOpen {
+    /**
+     * `short` (`https://brave-otter-48213.<domain>/`) or `long` (a longer, harder-to-guess URL,
+     * for apps with sensitive data). Absent: the project's setting, else the organization's,
+     * else `short`. Custom domains are coming soon.
+     */
+    length?: PreviewLinkLength | null;
     /**
      * 1–65535.
      */
@@ -3611,6 +3762,10 @@ export interface PortsRevoked {
     revoked: Array<string>;
     sandbox_id: string;
 }
+/**
+ * How long a preview URL is. Custom domains are coming soon.
+ */
+export type PreviewLinkLength = "short" | "long";
 /**
  * The free credit a new account gets. An account's own credit, and whether it can still claim
  * it, is `GET /v1/credits/offer`.
@@ -3884,8 +4039,9 @@ export interface ProjectMoved {
 export interface ProjectPatch {
     /**
      * Keep a failed sandbox so it can be reopened where it broke, when a run does not say
-     * (`capture`): `true` or `false`; `null` = the next level's setting. Set by an owner, on its
-     * own (no other field in the same request).
+     * (`capture`): `true` or `false`; `null` = not chosen, so the organization's choice applies,
+     * and where neither chose, the default: not kept unless the organization or project chose to
+     * keep them. Set by an owner, on its own (no other field in the same request).
      */
     failure_captures?: boolean | null;
     /**
@@ -3898,6 +4054,13 @@ export interface ProjectPatch {
      * sandbox ends, 1–30; `null` = the organization's setting. Set by an owner.
      */
     output_retention_days?: number | null;
+    /**
+     * The length of this project's new preview URLs when a request does not say: `short` or
+     * `long` (a longer, harder-to-guess URL, for apps with sensitive data); `null` = the
+     * organization's setting. Set by an owner, on its own (no other field in the same request).
+     * Custom domains are coming soon.
+     */
+    preview_link_length?: PreviewLinkLength | null;
 }
 /**
  * One project. API keys belong to a project; a project holds any number of repositories.
@@ -3912,10 +4075,18 @@ export interface ProjectView {
      */
     default: boolean;
     /**
-     * Whether this project's failed sandboxes are kept to reopen, when a run does not say
-     * (`capture`); `null` = the organization's setting. Set by an owner.
+     * This project's choice: whether its failed sandboxes are kept to reopen, when a run does not
+     * say (`capture`); `null` = not chosen, so the organization's choice applies, and where
+     * neither chose, the default: not kept unless the organization or project chose to keep
+     * them. Set by an owner. What applies is `failure_captures_effective`.
      */
     failure_captures?: boolean | null;
+    /**
+     * What applies to this project's failed runs when the run does not say (`capture`): kept or
+     * not, and which choice decided it (this project's, its organization's, or the default). A
+     * run's own `capture` is followed either way.
+     */
+    failure_captures_effective?: CapturesEffective | null;
     /**
      * Keys that still work.
      */
@@ -3942,6 +4113,11 @@ export interface ProjectView {
      * organization's setting. Set by an owner.
      */
     output_retention_days?: number | null;
+    /**
+     * The length of this project's new preview URLs when a request does not say (`length`):
+     * `short` or `long`; `null` = the organization's setting. Set by an owner.
+     */
+    preview_link_length?: PreviewLinkLength | null;
     project_id: string;
 }
 export interface Provenance {
@@ -5559,6 +5735,12 @@ export interface SecretStored {
      * of the `*`. Present when `hosts` is.
      */
     urls?: Array<string>;
+    /**
+     * Things to know about the value just stored, one `code: sentence` per line; absent when
+     * there are none. `api_key_value`: the value holds an API key of this service, which any
+     * command in a sandbox given this secret can use.
+     */
+    warnings?: Array<string>;
 }
 /**
  * One stored secret, without its value.