@miosa/sdk 3.2.3 → 3.2.5

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.3";
+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) {
@@ -8517,6 +8531,7 @@ function isCommandReady(payload) {
     return status === "ready";
   });
 }
+var READINESS_STREAM_MAX_TIMEOUT_SEC = 120;
 var SANDBOX_TEMPLATE = "miosa-sandbox";
 var SANDBOX_TIER_BY_CPU = {
   1: { size: "xs", memoryMb: 2048 },
@@ -8651,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,
@@ -8676,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 ?? "");
@@ -9144,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;
@@ -9157,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;
       }
     }
@@ -9171,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");
@@ -9181,7 +9229,7 @@ var Sandbox = class _Sandbox {
         method: "POST",
         body: execBody(command, options),
         signal: options?.signal,
-        ...execDeadline(options)
+        ...execStreamDeadline(options)
       }
     );
     return (async function* () {
@@ -9455,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 };
@@ -9565,47 +9622,66 @@ var Sandbox = class _Sandbox {
     );
   }
   /**
-   * 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.
    */
   async waitUntilReady(options = {}) {
     const timeout = options.timeout ?? 30;
     const stream = options.stream ?? true;
     const requireCommandReady = options.requireCommandReady ?? true;
+    const deadlineMs = Date.now() + timeout * 1e3;
     if (stream) {
-      const sseResult = await this.tryReadinessStream(timeout);
-      if (sseResult === true) {
-        await this.adoptReadyState();
-        return true;
-      }
-      if (sseResult === false) {
-        await this.throwIfTerminallyFailed();
-        return false;
+      while (true) {
+        const remainingMs = deadlineMs - Date.now();
+        if (remainingMs <= 0) return false;
+        const remainingSec = remainingMs / 1e3;
+        const clamped = remainingSec > READINESS_STREAM_MAX_TIMEOUT_SEC;
+        const windowSec = clamped ? READINESS_STREAM_MAX_TIMEOUT_SEC : remainingSec;
+        const sseResult = await this.tryReadinessStream(windowSec);
+        if (sseResult === true) {
+          await this.adoptReadyState();
+          return true;
+        }
+        if (sseResult === false) {
+          await this.throwIfTerminallyFailed();
+          if (!clamped || Date.now() >= deadlineMs) return false;
+          continue;
+        }
+        break;
       }
+      if (Date.now() >= deadlineMs) return false;
     }
-    const deadlineMs = Date.now() + timeout * 1e3;
     while (Date.now() < deadlineMs) {
       try {
         const data = await this.readiness();
@@ -9669,9 +9745,25 @@ var Sandbox = class _Sandbox {
    * stream endpoint is unavailable (404 or transport error) so callers
    * can fall back to polling.
    */
-  async tryReadinessStream(timeoutSec) {
+  /**
+   * 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.
+   */
+  async tryReadinessStream(windowSec) {
+    const clampedWindowSec = Math.max(
+      1,
+      Math.min(windowSec, READINESS_STREAM_MAX_TIMEOUT_SEC)
+    );
     const abort = new AbortController();
-    const timer = setTimeout(() => abort.abort(), (timeoutSec + 5) * 1e3);
+    const timer = setTimeout(
+      () => abort.abort(),
+      (clampedWindowSec + 5) * 1e3
+    );
     try {
       const headers = {
         Authorization: `Bearer ${this.http.apiKey}`,
@@ -9683,7 +9775,7 @@ var Sandbox = class _Sandbox {
         "User-Agent": SDK_USER_AGENT
       };
       const response = await fetch(
-        `${this.http.baseUrl}/sandboxes/${this.id}/readiness/stream`,
+        `${this.http.baseUrl}/sandboxes/${this.id}/readiness/stream?timeout=${clampedWindowSec}`,
         { method: "GET", headers, signal: abort.signal }
       );
       if (response.status === 404) return null;
@@ -9704,6 +9796,7 @@ var Sandbox = class _Sandbox {
               const evt = line.slice(6).trim();
               if (evt === "ready") return true;
               if (evt === "timeout") return false;
+              if (evt === "error") throw this.bootFailedError("error");
             }
           }
         }
@@ -9714,7 +9807,10 @@ var Sandbox = class _Sandbox {
         }
       }
       return null;
-    } catch {
+    } catch (err) {
+      if (err instanceof MiosaError && err.code === "SANDBOX_BOOT_FAILED") {
+        throw err;
+      }
       return null;
     } finally {
       clearTimeout(timer);
@@ -9765,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;
@@ -9860,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;
@@ -9872,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