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

package/dist/cjs/client.d.ts

@@ -178,6 +178,8 @@ export interface SandboxRef extends QueuedInfo {
 }
 /** How a grader's result is read. */
 export type ScoreMode = M.ScoreMode;
+/** Which of a run's sandboxes are kept to reopen where they ended (`RunStartOpts.capture`). */
+export type CaptureMode = M.CaptureMode;
 /**
  * Score the agent's work after the episode, in a clean copy of the snapshot with the agent's
  * changes applied. `holdout_cmd` is your own second test set; the report carries the gap
@@ -396,6 +398,12 @@ export interface SecretRecord {
     raw?: "allowed" | "refused";
     /** Whether the value is kept out of the bound hosts' answers (present when `hosts` is). */
     scan_responses?: boolean;
+    /**
+     * On `secrets.set` only: things to know about the value just stored, one `code: sentence` each;
+     * 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?: string[];
 }
 /**
  * `secrets.set` options: bind the secret to hosts. Requests a sandbox sends to the host's address
@@ -745,8 +753,25 @@ export interface OrgRecord {
     created_at: string;
     /** Days command output is kept after a sandbox ends; `null` = the default, 7. */
     output_retention_days?: number | null;
-    /** Keep a failed sandbox to reopen where it broke, when a run does not say; absent or `null` = the default. */
+    /**
+     * This organization's choice: keep a failed sandbox to reopen where it broke, when a run does not say (`capture`);
+     * absent or `null` = not chosen, so the default applies: not kept unless the organization or project chose to keep
+     * them. What applies is `failure_captures_effective`.
+     */
     failure_captures?: boolean | null;
+    /** The length of new preview URLs when a request does not say; absent or `null` = the default, short. */
+    preview_link_length?: PreviewLinkLength | null;
+    /** What applies to a failed run that does not say: kept or not, and whose choice decided it. */
+    failure_captures_effective?: CapturesEffective;
+}
+/**
+ * What applies to a failed run's sandboxes when the run does not say (`capture`): `kept`, and `from`, whose choice
+ * decided it: `project`, `org`, or `default` (neither chose: not kept unless the organization or project chose to
+ * keep them). A run's own `capture` is followed either way.
+ */
+export interface CapturesEffective {
+    kept: boolean;
+    from: "project" | "org" | "default" | (string & {});
 }
 export interface ProjectRecord {
     project_id: string;
@@ -758,8 +783,16 @@ export interface ProjectRecord {
     monthly_cap_usd?: number | null;
     /** Days this project's command output is kept after a sandbox ends; `null` = the organization's. */
     output_retention_days?: number | null;
-    /** Keep this project's failed sandboxes to reopen, when a run does not say; absent or `null` = the organization's. */
+    /**
+     * This project's choice: keep its failed sandboxes to reopen, when a run does not say (`capture`); absent or `null` =
+     * the organization's choice, and where neither chose, the default: not kept unless the organization or project
+     * chose to keep them. What applies is `failure_captures_effective`.
+     */
     failure_captures?: boolean | null;
+    /** The length of this project's new preview URLs when a request does not say; absent or `null` = the organization's. */
+    preview_link_length?: PreviewLinkLength | null;
+    /** What applies to its failed runs that do not say: kept or not, and whose choice decided it. */
+    failure_captures_effective?: CapturesEffective;
     created_at: string;
 }
 /** The longest command output may be kept after a sandbox ends, in days. */
@@ -1383,7 +1416,7 @@ export interface SshRevoked {
 export interface PortRecord {
     sandbox_id: string;
     port: number;
-    /** 256-bit capability; anyone with the URL reaches the port. */
+    /** The URL's own name: anyone with the URL reaches the port. Pass it to `revoke` to take this one URL down. */
     token: string;
     url: string;
     /** The same token as a DNS label, for a wildcard-DNS deployment (`<label>.<suffix>`). */
@@ -1391,6 +1424,25 @@ export interface PortRecord {
     created_unix_ns?: number;
     /** When the URL stops working on its own (`ttl_s`); `null` for one that works until revoked. */
     expires_unix_ns?: number | null;
+    /**
+     * `"short"` (`https://brave-otter-48213.<domain>/`, the default) or `"long"` (a longer,
+     * harder-to-guess URL, for apps with sensitive data).
+     */
+    length?: PreviewLinkLength;
+}
+/**
+ * How long a preview URL is: `"short"` (the default, `https://brave-otter-48213.<domain>/`) or
+ * `"long"` (a longer, harder-to-guess URL, for apps with sensitive data). Custom domains are
+ * coming soon.
+ */
+export type PreviewLinkLength = "short" | "long";
+/** Options of `ports.expose`. */
+export interface PortExposeOpts {
+    /**
+     * `"short"` or `"long"`. Omitted: the length the sandbox's project chose, else its
+     * organization's, else short.
+     */
+    length?: PreviewLinkLength;
 }
 /** A key named without its secret (`/me`'s `key`, the key lists). */
 export interface KeyRef {
@@ -1422,8 +1474,31 @@ export interface MeResponse {
         max_concurrency?: number;
         max_session_s?: number | null;
         max_sandbox_vcpus?: number | null;
+        /** Everything stored together, in GB: snapshots, paused sandboxes and saved failures; `null` for no limit. */
+        max_storage_gb?: number | null;
+        /**
+         * 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;
+        /** Snapshots that may be kept; `null` for no limit. */
+        max_snapshots?: number | null;
+        /** Paused sandboxes that may be kept; `null` for no limit. */
+        max_paused?: number | null;
         [extra: string]: number | null | undefined;
     };
+    /**
+     * What the organisation stores now, in bytes (a GB of `limits` is 2^30 bytes): everything together (`used_bytes`,
+     * against `limits.max_storage_gb`) and its saved failures (`captures_bytes`, against
+     * `limits.max_capture_storage_gb`), with the counts. Absent from a server before it.
+     */
+    storage?: {
+        used_bytes: number;
+        captures_bytes: number;
+        snapshots: number;
+        paused: number;
+        captures: number;
+    } | null;
     /**
      * Sandboxes holding capacity now (queued, starting, ready or running; paused ones hold none)
      * against the limit.
@@ -1603,6 +1678,12 @@ export interface RunStartOpts {
     verifyEach?: boolean;
     network?: NetworkMode;
     optimizeFor?: OptimizeFor;
+    /**
+     * Which of this run's sandboxes are kept to reopen where they ended (`runs.open`): `on_failure`
+     * keeps one whose command failed, `off` keeps none, `always` keeps every one. Left out, the
+     * default applies.
+     */
+    capture?: CaptureMode;
     /**
      * Secrets for every sandbox of this run. An `exec` is no longer required: a run that names
      * its secrets here gives them to every command run against every one of its sandboxes,
@@ -1666,9 +1747,9 @@ export interface ExecOpts {
      */
     secrets?: SecretBinding[];
     /**
-     * Cancel an in-flight exec, streamed or not: the client stops waiting and the request is closed,
-     * which ends the command in the sandbox. A buffered exec then throws `TimeoutError` ("aborted by
-     * the caller's signal"); a streamed one rejects with the signal's `AbortError`.
+     * Cancel an in-flight exec, streamed or not: the client stops waiting and tells the service to
+     * stop the command in the sandbox. A buffered exec then throws `TimeoutError` ("aborted by the
+     * caller's signal"); a streamed one rejects with the signal's `AbortError`.
      */
     signal?: AbortSignal;
     /**
@@ -2062,6 +2143,9 @@ export declare class PromigenceClient {
     private guardDispatcher;
     private dispatcherFor;
     private againKeyed;
+    private heldExec;
+    private reattachBuffered;
+    private cancelHeldExec;
     request<T>(opts: RequestOpts): Promise<T>;
     /**
      * A request whose body — in either direction — is **bytes, not JSON** (`files get|put`).
@@ -2259,15 +2343,29 @@ export declare class PromigenceClient {
             /** `PATCH /orgs/:org/projects/:project {name}` — rename it (the `default` project keeps its name). */
             rename: (org: string, project: string, name: string) => Promise<ProjectRecord>;
             /**
-             * `PATCH /orgs/:org/projects/:project` — rename it, set how long its command output is kept, or
-             * whether its failed sandboxes are kept to reopen (that one on its own). The settings need an owner signed in.
+             * `PATCH /orgs/:org/projects/:project` — rename it, set how long its command output is kept,
+             * whether its failed sandboxes are kept to reopen (on its own; `null` = the organization's choice, and
+             * where neither chose, not kept unless the organization or project chose to keep them), or how long
+             * its new preview URLs are (on its own). The settings need an owner signed in.
              */
             update: (org: string, project: string, update: {
                 name?: string;
                 outputRetentionDays?: number | null;
                 failureCaptures?: boolean | null;
+                previewLinkLength?: PreviewLinkLength | null;
             }) => Promise<ProjectRecord>;
         };
+        /**
+         * `PATCH /orgs/:org` — rename it, set how long its command output is kept, whether its failed
+         * sandboxes are kept to reopen, or how long its new preview URLs are (those two each on their
+         * own). The settings need an owner signed in.
+         */
+        update: (org: string, update: {
+            name?: string;
+            outputRetentionDays?: number | null;
+            failureCaptures?: boolean | null;
+            previewLinkLength?: PreviewLinkLength | null;
+        }) => Promise<OrgRecord>;
     };
     private group_orgs;
     readonly credits: {
@@ -2441,7 +2539,13 @@ export declare class PromigenceClient {
      */
     private waitLoop;
     readonly sandboxes: {
-        /** `POST /sandboxes/:id/execs` — foreground exec, inline output up to `maxOutputBytes`. */
+        /**
+         * `POST /sandboxes/:id/execs` — foreground exec, inline output up to `maxOutputBytes`.
+         *
+         * If the connection drops while the command runs, the SDK picks the command up again where the
+         * service keeps it and returns its own answer; when it cannot, it throws `ExecLostError`. The
+         * command is never sent a second time.
+         */
         exec: (sandboxId: string, opts: ExecOpts) => Promise<ExecResponse>;
         /**
          * `POST /sandboxes/:id/execs` with `Accept: text/event-stream`.
@@ -2453,6 +2557,10 @@ export declare class PromigenceClient {
          *
          * Uses `fetch`'s streaming body rather than `res.text()`, which is what `request()` does and
          * why it cannot be reused here: `await res.text()` is precisely the buffering this removes.
+         *
+         * If the connection drops while the command runs, the SDK picks the command up again where the
+         * service keeps it, and the stream goes on where it left off; when it cannot, it throws
+         * `ExecLostError`. The command is never sent a second time.
          */
         execStream: (sandboxId: string, opts: ExecOpts, on?: {
             stdout?: (chunk: Uint8Array) => void;
@@ -2547,7 +2655,12 @@ export declare class PromigenceClient {
          * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
          */
         ports: {
-            expose: (sandboxId: string, port: number) => Promise<PortRecord>;
+            /**
+             * Publish a port: `{ length: "long" }` for a longer, harder-to-guess URL (apps with
+             * sensitive data); omitted, the length the sandbox's project or organization chose
+             * (short by default).
+             */
+            expose: (sandboxId: string, port: number, opts?: PortExposeOpts) => Promise<PortRecord>;
             list: (sandboxId: string) => Promise<PortRecord[]>;
             /** A token revokes that URL; a port number revokes every URL for that port. */
             revoke: (sandboxId: string, tokenOrPort: string | number) => Promise<{