@miosa/sdk 3.2.3 → 3.2.5

package/dist/index.d.ts

@@ -5219,6 +5219,8 @@ interface MiosaErrorBody {
         message?: string;
         details?: unknown;
         retryable?: boolean;
+        request_id?: string;
+        retry_after_ms?: number;
     };
     message?: string;
     code?: string;
@@ -5227,6 +5229,7 @@ interface MiosaErrorBody {
     reason?: string;
     request_id?: string;
     retryable?: boolean;
+    retry_after_ms?: number;
 }
 declare class MiosaError extends Error {
     readonly status: number;
@@ -5234,8 +5237,21 @@ declare class MiosaError extends Error {
     readonly details: unknown;
     readonly requestId: string | undefined;
     readonly retryable: boolean;
-    constructor(message: string, status: number, code: string, details?: unknown, requestId?: string, retryable?: boolean);
-    static fromResponse(status: number, body: MiosaErrorBody, requestId?: string): MiosaError;
+    /**
+     * Server-supplied retry hint in milliseconds, taken from the canonical
+     * error shape's `retry_after_ms` (nested under `error` or top-level) or,
+     * failing that, the HTTP `Retry-After` header. `undefined` when the
+     * response carried neither, in which case a caller should fall back to
+     * its own backoff policy.
+     */
+    retryAfterMs: number | undefined;
+    constructor(message: string, status: number, code: string, details?: unknown, requestId?: string, retryable?: boolean, retryAfterMs?: number);
+    /**
+     * @param retryAfterHeaderMs The `Retry-After` header value, already
+     *   converted to milliseconds by the caller. Used only when the body does
+     *   not carry the more precise `retry_after_ms`.
+     */
+    static fromResponse(status: number, body: MiosaErrorBody, requestId?: string, retryAfterHeaderMs?: number): MiosaError;
 }
 declare class AuthError extends MiosaError {
     constructor(message: string, status?: number, code?: string, details?: unknown, requestId?: string, retryable?: boolean);
@@ -6732,7 +6748,7 @@ type SandboxSize = "xs" | "small" | "medium" | "large" | "xl";
 type SandboxId = string & {
     readonly __brand: "SandboxId";
 };
-type SandboxState = "provisioning" | "running" | "paused" | "destroying" | "destroyed" | "error";
+type SandboxState = "provisioning" | "running" | "pausing" | "paused" | "resuming" | "stopped" | "destroying" | "destroyed" | "error";
 interface SandboxCreateParams {
     templateId?: string;
     template_id?: string;
@@ -6827,8 +6843,18 @@ interface SandboxCreateParams {
 }
 interface SandboxGetOrCreateParams extends SandboxCreateParams {
     name: string;
-    /** Resume an existing paused sandbox before returning it. Defaults to true. */
+    /**
+     * Resume an existing sandbox before returning it, when it is `paused`,
+     * `stopped` (persistent sandboxes only), or - after a bounded wait - lands
+     * in one of those states from `pausing`. Defaults to true.
+     */
     resume?: boolean;
+    /**
+     * Bound on how long to wait out an in-progress `pausing` transition before
+     * attempting resume, in seconds. The server's own pause work is typically
+     * well under this. Defaults to 30.
+     */
+    pausingWaitTimeoutSec?: number;
     /**
      * Wait for readiness before returning a created/resumed sandbox. Defaults to false.
      *
@@ -6861,6 +6887,18 @@ interface SandboxExecOptions {
     timeout?: number;
     timeoutSec?: number;
     timeout_sec?: number;
+    /**
+     * `exec.stream` only. Budget (seconds) reserved for the sandbox to wake
+     * and resume before the command's own `timeoutSec` starts counting down,
+     * separate from it. The server opens the SSE response, runs
+     * `ensure_running` (which resumes a paused sandbox), and only then starts
+     * the command's own timeout - so without a separate budget a slow resume
+     * could abort a command client-side while it is still within its own
+     * server-side deadline. Defaults to {@link DEFAULT_EXEC_WAKE_BUDGET_SEC}.
+     * Has no effect when `timeoutSec` is omitted (the stream is unbounded).
+     */
+    wakeTimeoutSec?: number;
+    wake_timeout_sec?: number;
 }
 interface SandboxExecResult {
     stdout: string;
@@ -6869,6 +6907,14 @@ interface SandboxExecResult {
     exit_code: number;
     durationMs?: number;
     duration_ms?: number;
+    /**
+     * True when the server killed the command for exceeding its timeout.
+     * Without this, a timeout was indistinguishable from the infra error
+     * frame, which also reports `exitCode: -1`. Absent when the server did
+     * not report it (older servers, or a non-timeout exit).
+     */
+    timedOut?: boolean;
+    timed_out?: boolean;
 }
 interface SandboxExportFile {
     path: string;
@@ -6902,7 +6948,10 @@ interface SandboxExportParams {
  * The server tags each SSE frame with an `event:` name (`stdout` / `stderr` /
  * `exit`); the SDK maps that name onto `type`. For output frames `data` (and
  * its legacy alias `line`) carry the text chunk. The exit frame carries the
- * process exit code as both `exit_code` and its camelCase alias `exitCode`.
+ * process exit code as both `exit_code` and its camelCase alias `exitCode`,
+ * plus `timed_out`/`timedOut` when the server reports it (see B1-9: without
+ * this a timeout was indistinguishable from the infra error frame, which
+ * also reports `exit_code: -1`).
  */
 type SandboxExecEvent = {
     type: "stdout";
@@ -6916,6 +6965,8 @@ type SandboxExecEvent = {
     type: "exit";
     exit_code: number;
     exitCode: number;
+    timed_out?: boolean;
+    timedOut?: boolean;
 };
 interface SandboxExecRunner {
     (command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
@@ -7457,6 +7508,17 @@ declare class Sandbox {
         [key: string]: unknown;
     }>;
     pause(): Promise<Sandbox>;
+    /**
+     * Resume a paused (or persistent-stopped) sandbox.
+     *
+     * Always sends an `Idempotency-Key`, generating a fresh one when the
+     * caller doesn't supply one - same rationale as {@link generateIdempotencyKey}
+     * for create(): the key is built once here and threaded through a single
+     * `HttpClient.request` call, whose headers are fixed before its retry loop
+     * runs, so every retry of *this* resume replays the same key. Without this,
+     * a client-side retry of a slow resume could dispatch a second full resume
+     * execution (re-running host reservation) instead of deduping server-side.
+     */
     resume(idempotencyKey?: string): Promise<Sandbox>;
     deploy(params?: SandboxDeployParams): Promise<Record<string, unknown>>;
     deployDocker(params?: SandboxDeployParams): Promise<Record<string, unknown>>;
@@ -7468,30 +7530,39 @@ declare class Sandbox {
     /** Check readiness of the sandbox (GET /sandboxes/:id/readiness). */
     readiness(): Promise<Record<string, unknown>>;
     /**
-     * Block until the sandbox reports ready, or *timeout* seconds elapse.
+     * Block until the sandbox reports ready, or the caller's *timeout* seconds
+     * (the full deadline budget) elapse.
      *
-     * When `stream` is `true` (the default) this opens an SSE connection
-     * to `GET /sandboxes/:id/readiness/stream` and waits for an
-     * `event: ready` frame. The server emits `ready` immediately if the
-     * sandbox is already ready, otherwise as soon as the readiness PubSub
-     * message fires.
+     * When `stream` is `true` (the default) this opens an SSE connection to
+     * `GET /sandboxes/:id/readiness/stream?timeout=<window>` and waits for an
+     * `event: ready` frame. `<window>` is the caller's remaining budget clamped
+     * to {@link READINESS_STREAM_MAX_TIMEOUT_SEC}, the server's own maximum
+     * lease for a single stream connection — a long-restoring persistent
+     * sandbox (e.g. Docker restore, 60-90 s) legitimately outlives one lease.
+     * The server emits `ready` immediately if the sandbox is already ready,
+     * `event: timeout` when *that connection's* window elapses without a
+     * verdict, and `event: error` on a terminal boot failure.
      *
-     * Returns `true` once the sandbox is ready, `false` on `event: timeout`
-     * or when the local timeout elapses before ready.
+     * An `event: timeout` (or the stream closing without a verdict) is NOT
+     * treated as the final answer while the caller's overall deadline still has
+     * budget left — that would silently truncate a 180 s wait down to the
+     * server's lease window and return `false` while the sandbox was still
+     * mid-restore. Instead this reconnects the stream (or falls back to
+     * polling) for the remaining budget. `false` is only returned once the
+     * caller's full deadline has elapsed.
      *
      * Throws {@link MiosaError} with code `SANDBOX_BOOT_FAILED` as soon as the
      * sandbox is observed in a terminal failure state (`error` or `destroyed`)
      * while waiting, instead of silently exhausting the timeout and returning
      * `false` — a permanent boot failure and "still booting, keep waiting" must
-     * never look the same to the caller. The readiness SSE stream itself has no
-     * dedicated failure event today (the server only ever emits
-     * `ready`/`status`/`timeout`), so on `event: timeout` this makes one
-     * authoritative {@link readiness} check before giving up, to catch a
-     * failure that landed right at the boundary.
+     * never look the same to the caller. On each `event: timeout` boundary this
+     * also makes one authoritative {@link readiness} check before deciding to
+     * reconnect or stop, to catch a failure that landed right at the boundary.
      *
      * If the SSE endpoint returns 404 (server pre-dates the streaming
      * endpoint) this transparently falls back to polling {@link readiness}
-     * every 10 ms until ready, timeout, or terminal failure.
+     * every 10 ms until ready, the caller's deadline elapses, or terminal
+     * failure.
      */
     waitUntilReady(options?: {
         timeout?: number;
@@ -7522,6 +7593,15 @@ declare class Sandbox {
      * stream endpoint is unavailable (404 or transport error) so callers
      * can fall back to polling.
      */
+    /**
+     * Opens one readiness SSE connection for at most *windowSec* seconds (this
+     * is a single lease, not the caller's overall {@link waitUntilReady}
+     * budget — see there for how leases are chained). *windowSec* is sent to
+     * the server as `?timeout=<seconds>` so the server's own stream deadline
+     * matches what was actually requested instead of always falling back to
+     * its 30 s default, which is what let a 180 s `waitUntilReady` call get
+     * cut short at 30 s.
+     */
     private tryReadinessStream;
     destroy(): Promise<void>;
     delete(): Promise<void>;
@@ -7557,9 +7637,14 @@ declare class Sandboxes {
     /**
      * Idempotently obtain a persistent sandbox by stable name.
      *
-     * If the sandbox exists, it is returned. If it is paused and `resume !== false`,
-     * it is resumed first. If it does not exist, it is created with the supplied
-     * params. Destroyed sandboxes are permanent and are not resumed by this helper.
+     * If the sandbox exists, it is returned. Unless `resume === false`: a
+     * `paused` or persistent `stopped` sandbox is resumed; a `pausing`
+     * sandbox is waited out (bounded by `pausingWaitTimeoutSec`) and then
+     * resumed if it landed on `paused`/`stopped`; a resume answered with a
+     * 409 the server marks `retryable: true` (e.g. a concurrent pause still
+     * finishing) is retried using the server's `retry_after_ms` hint. If the
+     * sandbox does not exist, it is created with the supplied params.
+     * Destroyed sandboxes are permanent and are not resumed by this helper.
      */
     getOrCreate(params: SandboxGetOrCreateParams): Promise<Sandbox>;
     delete(id: SandboxId | string): Promise<void>;