@miosa/sdk 3.2.4 → 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>>;
@@ -7575,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>;

package/dist/index.js

@@ -18,7 +18,15 @@ var MiosaError = class _MiosaError extends Error {
   details;
   requestId;
   retryable;
-  constructor(message, status, code, details, requestId, retryable = defaultRetryable(status)) {
+  /**
+   * 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;
+  constructor(message, status, code, details, requestId, retryable = defaultRetryable(status), retryAfterMs) {
     super(message);
     this.name = "MiosaError";
     this.status = status;
@@ -26,34 +34,33 @@ var MiosaError = class _MiosaError extends Error {
     this.details = details;
     this.requestId = requestId;
     this.retryable = retryable;
+    this.retryAfterMs = retryAfterMs;
   }
-  static fromResponse(status, body5, requestId) {
+  /**
+   * @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, body5, requestId, retryAfterHeaderMs2) {
     const nested = typeof body5.error === "object" ? body5.error : void 0;
     const flatError = typeof body5.error === "string" ? body5.error : void 0;
     const flatErrorIsCode = !!flatError && /^[A-Z][A-Z0-9_]+$/.test(flatError);
     const message = nested?.message ?? body5.message ?? body5.detail ?? body5.reason ?? flatError ?? `HTTP ${status}`;
     const code = nested?.code ?? body5.code ?? (flatErrorIsCode ? flatError : "UNKNOWN_ERROR");
     const details = nested?.details ?? body5.details ?? (body5.detail || body5.reason ? { detail: body5.detail, reason: body5.reason } : void 0);
-    requestId ??= body5.request_id;
+    requestId ??= nested?.request_id ?? body5.request_id;
     const retryable = nested?.retryable ?? body5.retryable ?? defaultRetryable(status);
+    const retryAfterMs = nested?.retry_after_ms ?? body5.retry_after_ms ?? retryAfterHeaderMs2;
     const connectError = connectErrorFromCode(code, message, status, details, requestId, retryable);
-    if (connectError) return connectError;
-    if (status === 401 || status === 403) {
-      return new AuthError(message, status, code, details, requestId, retryable);
-    }
-    if (status === 404) {
-      return new NotFoundError(message, code, details, requestId, retryable);
-    }
-    if (status === 429) {
-      return new RateLimitError(message, details, requestId, void 0, retryable);
-    }
-    if (status === 402) {
-      return new InsufficientCreditsError(message, details, requestId, retryable);
-    }
-    if (status >= 400 && status < 500) {
-      return new ValidationError(message, status, code, details, requestId, retryable);
-    }
-    return new _MiosaError(message, status, code, details, requestId, retryable);
+    const built = connectError ?? (status === 401 || status === 403 ? new AuthError(message, status, code, details, requestId, retryable) : status === 404 ? new NotFoundError(message, code, details, requestId, retryable) : status === 429 ? new RateLimitError(
+      message,
+      details,
+      requestId,
+      retryAfterMs === void 0 ? void 0 : retryAfterMs / 1e3,
+      retryable
+    ) : status === 402 ? new InsufficientCreditsError(message, details, requestId, retryable) : status >= 400 && status < 500 ? new ValidationError(message, status, code, details, requestId, retryable) : new _MiosaError(message, status, code, details, requestId, retryable));
+    built.retryAfterMs = retryAfterMs;
+    return built;
   }
 };
 function connectErrorFromCode(code, message, status, details, requestId, retryable) {
@@ -174,7 +181,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "3.2.4";
+var SDK_VERSION = "3.2.5";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -206,15 +213,18 @@ async function ensureHttp2Agent() {
 ensureHttp2Agent();
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
-var RETRY_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var BASE_DELAY_MS = 500;
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function retryDelay(attempt, retryAfterHeader) {
-  if (retryAfterHeader !== null) {
-    const seconds = parseInt(retryAfterHeader, 10);
-    if (!isNaN(seconds)) return seconds * 1e3;
+function retryAfterHeaderMs(retryAfterHeader) {
+  if (retryAfterHeader === null) return void 0;
+  const seconds = parseInt(retryAfterHeader, 10);
+  return isNaN(seconds) ? void 0 : seconds * 1e3;
+}
+function retryDelay(attempt, hintMs) {
+  if (hintMs !== void 0 && Number.isFinite(hintMs) && hintMs >= 0) {
+    return hintMs;
   }
   return BASE_DELAY_MS * 2 ** attempt + Math.random() * 100;
 }
@@ -289,7 +299,9 @@ var HttpClient = class {
         clearTimeout(timer);
         if (!response.ok) {
           const requestId = response.headers.get("x-request-id") ?? void 0;
-          const retryAfter = response.headers.get("retry-after");
+          const retryAfterMs = retryAfterHeaderMs(
+            response.headers.get("retry-after")
+          );
           let errorBody = {};
           try {
             errorBody = await response.json();
@@ -298,11 +310,12 @@ var HttpClient = class {
           const error = MiosaError.fromResponse(
             response.status,
             errorBody,
-            requestId
+            requestId,
+            retryAfterMs
           );
-          if (RETRY_STATUS.has(response.status) && attempt < maxRetries) {
+          if (error.retryable && attempt < maxRetries) {
             lastError = error;
-            await sleep(retryDelay(attempt, retryAfter));
+            await sleep(retryDelay(attempt, error.retryAfterMs));
             continue;
           }
           throw error;
@@ -333,7 +346,7 @@ var HttpClient = class {
           );
           if (attempt < maxRetries) {
             lastError = networkErr;
-            await sleep(retryDelay(attempt, null));
+            await sleep(retryDelay(attempt, void 0));
             continue;
           }
           throw networkErr;
@@ -437,7 +450,8 @@ var HttpClient = class {
         throw MiosaError.fromResponse(
           response.status,
           errorBody,
-          response.headers.get("x-request-id") ?? void 0
+          response.headers.get("x-request-id") ?? void 0,
+          retryAfterHeaderMs(response.headers.get("retry-after"))
         );
       }
       if (!response.body) {
@@ -8652,16 +8666,29 @@ function raiseUnresolvableShape(cpuCount, memoryMb, tier) {
     `Unsupported cpu/memory combination (${supplied}). Supported tiers: xs (1/2048), small (2/4096), medium (4/8192), large (8/16384), xl (16/32768). Pass a matching cpuCount + memoryMb (any diskSizeMb is allowed), use size, or supply cpuCount, memoryMb, and diskSizeMb together for a custom shape.`
   );
 }
-function execDeadline(options) {
+function validatedExecSeconds(options) {
   const seconds = options?.timeout ?? options?.timeoutSec ?? options?.timeout_sec;
-  if (seconds === void 0) return {};
+  if (seconds === void 0) return void 0;
   if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 86400) {
     throw new RangeError(
       "Exec timeout must be greater than zero and at most 86400 seconds"
     );
   }
+  return seconds;
+}
+function execDeadline(options) {
+  const seconds = validatedExecSeconds(options);
+  if (seconds === void 0) return {};
   return { timeout: seconds * 1e3 + 5e3 };
 }
+var DEFAULT_EXEC_WAKE_BUDGET_SEC = 60;
+function execStreamDeadline(options) {
+  const seconds = validatedExecSeconds(options);
+  if (seconds === void 0) return {};
+  const wakeSeconds = options?.wakeTimeoutSec ?? options?.wake_timeout_sec;
+  const wakeBudgetSec = wakeSeconds !== void 0 ? Math.max(0, wakeSeconds) : DEFAULT_EXEC_WAKE_BUDGET_SEC;
+  return { timeout: (seconds + wakeBudgetSec) * 1e3 + 5e3 };
+}
 function execBody(command, options = {}) {
   return stripUndefined26({
     command,
@@ -8677,7 +8704,14 @@ function normalizeExecEvent(event, payload) {
     const code = Number(
       record.exit_code ?? record.exitCode ?? (typeof payload === "number" ? payload : 0)
     );
-    return { type: "exit", exit_code: code, exitCode: code };
+    const timedOutRaw = record.timed_out ?? record.timedOut;
+    const timedOut = typeof timedOutRaw === "boolean" ? timedOutRaw : void 0;
+    return {
+      type: "exit",
+      exit_code: code,
+      exitCode: code,
+      ...timedOut !== void 0 ? { timed_out: timedOut, timedOut } : {}
+    };
   }
   const type = event === "stderr" ? "stderr" : "stdout";
   const data = typeof payload === "string" ? payload : String(record.line ?? record.data ?? "");
@@ -9145,12 +9179,18 @@ var Sandbox = class _Sandbox {
       result.durationMs = response.duration_ms;
       result.duration_ms = response.duration_ms;
     }
+    const timedOutRaw = response.timed_out ?? response.timedOut;
+    if (typeof timedOutRaw === "boolean") {
+      result.timedOut = timedOutRaw;
+      result.timed_out = timedOutRaw;
+    }
     return result;
   }
   async runCancellableExec(command, options) {
     let stdout = "";
     let stderr = "";
     let exitCode;
+    let timedOut;
     for await (const event of this.execStream(command, options)) {
       if (event.type === "stdout" && typeof event.line === "string")
         stdout += event.line;
@@ -9158,6 +9198,7 @@ var Sandbox = class _Sandbox {
         stderr += event.line;
       if (event.type === "exit" && typeof event.exit_code === "number") {
         exitCode = event.exit_code;
+        timedOut = event.timed_out;
         break;
       }
     }
@@ -9172,7 +9213,13 @@ var Sandbox = class _Sandbox {
         false
       );
     }
-    return { stdout, stderr, exitCode, exit_code: exitCode };
+    return {
+      stdout,
+      stderr,
+      exitCode,
+      exit_code: exitCode,
+      ...timedOut !== void 0 ? { timedOut, timed_out: timedOut } : {}
+    };
   }
   execStream(command, options) {
     this.assertRunning("exec.stream");
@@ -9182,7 +9229,7 @@ var Sandbox = class _Sandbox {
         method: "POST",
         body: execBody(command, options),
         signal: options?.signal,
-        ...execDeadline(options)
+        ...execStreamDeadline(options)
       }
     );
     return (async function* () {
@@ -9456,17 +9503,26 @@ var Sandbox = class _Sandbox {
     this.data = { ...this.data, ...data };
     return this;
   }
+  /**
+   * 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.
+   */
   async resume(idempotencyKey11) {
-    const response = idempotencyKey11 ? await this.http.request(
+    const key = idempotencyKey11 ?? generateIdempotencyKey();
+    const response = await this.http.request(
       `/sandboxes/${this.id}/resume`,
       {
         method: "POST",
         body: {},
-        headers: { "Idempotency-Key": idempotencyKey11 }
+        headers: { "Idempotency-Key": key }
       }
-    ) : await this.http.post(
-      `/sandboxes/${this.id}/resume`,
-      {}
     );
     const data = unwrap48(response);
     this.data = { ...this.data, ...data };
@@ -9805,6 +9861,50 @@ var Sandbox = class _Sandbox {
     }
   }
 };
+function sleep8(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isResumableState(state) {
+  return state === "paused" || state === "stopped";
+}
+var DEFAULT_PAUSING_WAIT_TIMEOUT_SEC = 30;
+var PAUSING_POLL_INTERVAL_MS = 500;
+var RESUME_RETRY_MAX_ATTEMPTS = 5;
+var RESUME_RETRY_FALLBACK_DELAY_MS = 500;
+async function waitOutPausingState(sandbox, timeoutSec) {
+  const deadline = Date.now() + timeoutSec * 1e3;
+  while (sandbox.state === "pausing" && Date.now() < deadline) {
+    await sleep8(PAUSING_POLL_INTERVAL_MS);
+    try {
+      await sandbox.refresh();
+    } catch {
+    }
+  }
+}
+async function resumeWithRetryHint(sandbox) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await sandbox.resume();
+      return;
+    } catch (error) {
+      const canRetry = error instanceof MiosaError && error.status === 409 && error.retryable === true && attempt < RESUME_RETRY_MAX_ATTEMPTS;
+      if (!canRetry) throw error;
+      await sleep8(error.retryAfterMs ?? RESUME_RETRY_FALLBACK_DELAY_MS);
+    }
+  }
+}
+async function resumeForGetOrCreate(sandbox, params) {
+  if (params.resume === false) return;
+  if (sandbox.state === "pausing") {
+    await waitOutPausingState(
+      sandbox,
+      params.pausingWaitTimeoutSec ?? DEFAULT_PAUSING_WAIT_TIMEOUT_SEC
+    );
+  }
+  if (isResumableState(sandbox.state)) {
+    await resumeWithRetryHint(sandbox);
+  }
+}
 var Sandboxes = class {
   constructor(http) {
     this.http = http;
@@ -9900,9 +10000,14 @@ var Sandboxes = class {
   /**
    * 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.
    */
   async getOrCreate(params) {
     let sandbox;
@@ -9912,9 +10017,7 @@ var Sandboxes = class {
       if (!(error instanceof NotFoundError)) throw error;
       sandbox = await this.create(params);
     }
-    if (sandbox.state === "paused" && params.resume !== false) {
-      await sandbox.resume();
-    }
+    await resumeForGetOrCreate(sandbox, params);
     if (params.waitUntilReady === true) {
       const ready = await sandbox.waitUntilReady({
         timeout: params.waitTimeoutSec ?? 60