@miosa/sdk 3.1.0 → 3.2.1

package/dist/index.d.ts

@@ -7432,14 +7432,34 @@ declare class Sandbox {
      * Returns `true` once the sandbox is ready, `false` on `event: timeout`
      * or when the local timeout elapses before ready.
      *
+     * 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.
+     *
      * 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 or timeout.
+     * endpoint) this transparently falls back to polling {@link readiness}
+     * every 10 ms until ready, timeout, or terminal failure.
      */
     waitUntilReady(options?: {
         timeout?: number;
         stream?: boolean;
+        /**
+         * Require the sandbox to be *command-ready* (exec will succeed) before
+         * resolving `true`, not merely aggregate-`ready`. Defaults to `true` so a
+         * resolved wait guarantees exec won't 409 SANDBOX_NOT_COMMAND_READY. Set
+         * `false` for the legacy aggregate-ready semantics.
+         */
+        requireCommandReady?: boolean;
     }): Promise<boolean>;
+    private bootFailedError;
+    /** Best-effort final check so an SSE `event: timeout` does not mask a boot failure that just landed. */
+    private throwIfTerminallyFailed;
     /**
      * Readiness answers from the server; `assertRunning` reads the local
      * snapshot. Leaving that snapshot behind meant a caller could await

package/dist/index.js

@@ -168,7 +168,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "3.1.0";
+var SDK_VERSION = "3.2.1";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -373,7 +373,7 @@ var HttpClient = class {
   async *streamFrames(path, options = {}) {
     const method = options.method ?? "GET";
     let headers = this.baseHeaders({
-      Accept: "text/event-stream",
+      Accept: "text/event-stream, application/json, */*",
       ...options.headers
     });
     let body5 = null;
@@ -8451,6 +8451,36 @@ function encodeContent(content) {
   for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
   return btoa(bin);
 }
+function generateIdempotencyKey() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = Math.random() * 16 | 0;
+    const v = ch === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var PLATFORM_READINESS_COMPONENTS = [
+  "command_agent",
+  "process_control",
+  "resource_contract",
+  "clock",
+  "identity",
+  "durability",
+  "filesystem",
+  "internal_probe"
+];
+function isCommandReady(payload) {
+  if (payload["ready"] === true) return true;
+  const readiness = payload["readiness"];
+  const components = readiness?.["components"] ?? payload["components"] ?? payload["readiness_components"];
+  if (!components || typeof components !== "object") return false;
+  return PLATFORM_READINESS_COMPONENTS.every((name) => {
+    const comp = components[name];
+    const status = typeof comp === "string" ? comp : comp?.status;
+    return status === "ready";
+  });
+}
 var SANDBOX_TEMPLATE = "miosa-sandbox";
 var SANDBOX_TIER_BY_CPU = {
   1: { size: "xs", memoryMb: 2048 },
@@ -8459,6 +8489,9 @@ var SANDBOX_TIER_BY_CPU = {
   8: { size: "large", memoryMb: 16384 },
   16: { size: "xl", memoryMb: 32768 }
 };
+function isTerminalSandboxFailure(state) {
+  return state === "error" || state === "destroyed";
+}
 var AGENT_WORKSPACE_TIMEOUT_SEC = 86400;
 var AGENT_WORKSPACE_IDLE_TIMEOUT_SEC = 1800;
 var AGENT_WORKSPACE_SNAPSHOT_EXPIRATION_DAYS = 30;
@@ -9432,34 +9465,77 @@ var Sandbox = class _Sandbox {
    * Returns `true` once the sandbox is ready, `false` on `event: timeout`
    * or when the local timeout elapses before ready.
    *
+   * 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.
+   *
    * 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 or timeout.
+   * endpoint) this transparently falls back to polling {@link readiness}
+   * every 10 ms until ready, timeout, or terminal failure.
    */
   async waitUntilReady(options = {}) {
     const timeout = options.timeout ?? 30;
     const stream = options.stream ?? true;
+    const requireCommandReady = options.requireCommandReady ?? true;
     if (stream) {
       const sseResult = await this.tryReadinessStream(timeout);
-      if (sseResult !== null) {
-        if (sseResult) await this.adoptReadyState();
-        return sseResult;
+      if (sseResult === true) {
+        await this.adoptReadyState();
+        return true;
+      }
+      if (sseResult === false) {
+        await this.throwIfTerminallyFailed();
+        return false;
       }
     }
     const deadlineMs = Date.now() + timeout * 1e3;
     while (Date.now() < deadlineMs) {
       try {
         const data = await this.readiness();
-        if (data.ready === true || data.status === "ready") {
+        const ready = requireCommandReady ? isCommandReady(data) : data.ready === true || data.status === "ready";
+        if (ready) {
           await this.adoptReadyState();
           return true;
         }
-      } catch {
+        if (isTerminalSandboxFailure(data.state)) {
+          throw this.bootFailedError(data.state);
+        }
+      } catch (err) {
+        if (err instanceof MiosaError && err.code === "SANDBOX_BOOT_FAILED") {
+          throw err;
+        }
       }
       await new Promise((resolve) => setTimeout(resolve, 10));
     }
     return false;
   }
+  bootFailedError(state) {
+    return new MiosaError(
+      `Sandbox ${this.id} entered terminal state '${state}' while waiting for readiness`,
+      502,
+      "SANDBOX_BOOT_FAILED",
+      { sandbox_id: this.id, state }
+    );
+  }
+  /** Best-effort final check so an SSE `event: timeout` does not mask a boot failure that just landed. */
+  async throwIfTerminallyFailed() {
+    try {
+      const data = await this.readiness();
+      if (isTerminalSandboxFailure(data?.state)) {
+        throw this.bootFailedError(data.state);
+      }
+    } catch (err) {
+      if (err instanceof MiosaError && err.code === "SANDBOX_BOOT_FAILED") {
+        throw err;
+      }
+    }
+  }
   /**
    * Readiness answers from the server; `assertRunning` reads the local
    * snapshot. Leaving that snapshot behind meant a caller could await
@@ -9486,7 +9562,11 @@ var Sandbox = class _Sandbox {
     try {
       const headers = {
         Authorization: `Bearer ${this.http.apiKey}`,
-        Accept: "text/event-stream",
+        // Combined defensively: a bare `text/event-stream` Accept header 406s
+        // on some `:accepts`-guarded routes (seen on the databases stream
+        // route). Offering json/`*/*` as fallbacks is free when SSE is
+        // actually returned.
+        Accept: "text/event-stream, application/json, */*",
         "User-Agent": SDK_USER_AGENT
       };
       const response = await fetch(
@@ -9595,14 +9675,12 @@ var Sandboxes = class {
     });
   }
   async create(params = {}) {
-    const idempotencyKey11 = params.idempotencyKey ?? params.idempotency_key;
+    const idempotencyKey11 = params.idempotencyKey ?? params.idempotency_key ?? generateIdempotencyKey();
     const requestOptions = {
       method: "POST",
-      body: createBody(params)
+      body: createBody(params),
+      headers: { "Idempotency-Key": idempotencyKey11 }
     };
-    if (idempotencyKey11) {
-      requestOptions.headers = { "Idempotency-Key": idempotencyKey11 };
-    }
     const data = unwrap48(
       await this.http.request(
         "/sandboxes",