@miosa/sdk 3.2.2 → 3.2.4

package/README.md

@@ -268,6 +268,23 @@ await sbx.pause();
 await sbx.resume();
 ```
 
+### Cancelling sandbox commands
+
+Pass an `AbortSignal` to `sandbox.exec.run(command, { signal, timeoutSec })` or `sandbox.exec.stream(command, { signal, timeoutSec })`.
+Aborting rejects with the signal's abort reason (an `AbortError` by default); it does not return a successful exit code or replay the command.
+Signal-bearing `exec.run` uses the request-owned stream and aggregates its exact stdout, stderr, and terminal exit code.
+If that stream ends without an exit event, `exec.run` rejects with `EXEC_STREAM_INCOMPLETE` (502, not retryable).
+Ordinary execution without a signal keeps the standard exec endpoint.
+An explicit `timeoutSec` sets the guest deadline and allows five additional seconds for its response.
+A guest that overruns that deadline rejects with `TimeoutError`, never with `AbortError`.
+Cancellation requires the server's request-owned streaming implementation and the guest's process-group cancellation support.
+
+### Confirming sandbox deletion
+
+`sandbox.destroy()` acknowledges deletion and updates the handle to the server's state.
+If deletion is still in progress, the handle reports `destroying` and exposes `sandbox.data.operation_id` when supplied by the server.
+Use `sandbox.refresh()` to verify completion; an acknowledgement alone does not prove resource cleanup.
+
 ## Publish from sandbox
 
 Preview is mutable; publish creates a durable deployment version. Static output
@@ -414,6 +431,7 @@ try {
 ```
 
 The SDK retries `429` and `5xx` automatically (3 retries, exponential backoff + jitter). Set `maxRetries: 0` to disable.
+Sandbox `exec` requests are never retried, because a replayed command would run twice; see [Cancelling sandbox commands](#cancelling-sandbox-commands).
 Every `MiosaError` carries `retryable` (server-supplied when present, otherwise `true` for 408/429/5xx and transport failures) and `requestId` for support correlation.
 
 ## Configuration

package/dist/index.d.ts

@@ -6,6 +6,10 @@ interface RequestOptions {
     headers?: Record<string, string>;
     body?: unknown;
     timeout?: number;
+    /** Cancel this request and its response stream without retrying. */
+    signal?: AbortSignal | undefined;
+    /** Override retries for operations which cannot safely be replayed. */
+    maxRetries?: number;
     /** Return raw Response instead of parsing JSON */
     rawResponse?: boolean;
     /** Send body as multipart/form-data */
@@ -6728,7 +6732,7 @@ type SandboxSize = "xs" | "small" | "medium" | "large" | "xl";
 type SandboxId = string & {
     readonly __brand: "SandboxId";
 };
-type SandboxState = "provisioning" | "running" | "paused" | "destroyed" | "error";
+type SandboxState = "provisioning" | "running" | "paused" | "destroying" | "destroyed" | "error";
 interface SandboxCreateParams {
     templateId?: string;
     template_id?: string;
@@ -6848,6 +6852,8 @@ interface SandboxListParams {
     external_project_id?: string;
 }
 interface SandboxExecOptions {
+    /** Abort the request-scoped execution, including its response stream. */
+    signal?: AbortSignal;
     cwd?: string;
     workingDir?: string;
     working_dir?: string;
@@ -6917,6 +6923,8 @@ interface SandboxExecRunner {
     stream(command: string, options?: SandboxExecOptions): AsyncIterableIterator<SandboxExecEvent>;
 }
 interface SandboxData {
+    operation_id?: string | null;
+    request_id?: string | null;
     id: SandboxId;
     state: SandboxState;
     slug?: string;
@@ -7372,6 +7380,7 @@ declare class Sandbox {
      */
     prompt(prompt: string, options?: SandboxPromptOptions): Promise<AgentRun>;
     private runExec;
+    private runCancellableExec;
     private execStream;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     download(path: string): Promise<Uint8Array>;
@@ -7459,30 +7468,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;
@@ -7513,6 +7531,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>;

package/dist/index.js

@@ -174,7 +174,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "3.2.2";
+var SDK_VERSION = "3.2.4";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -271,8 +271,12 @@ var HttpClient = class {
       fetchBody = JSON.stringify(body5);
     }
     let lastError;
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+    const maxRetries = options.maxRetries ?? this.maxRetries;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      options.signal?.throwIfAborted();
       const controller = new AbortController();
+      const cancel = () => controller.abort(options.signal?.reason);
+      options.signal?.addEventListener("abort", cancel, { once: true });
       const timer = setTimeout(() => controller.abort(), timeout);
       try {
         const response = await fetch(this.buildUrl(path), {
@@ -296,7 +300,7 @@ var HttpClient = class {
             errorBody,
             requestId
           );
-          if (RETRY_STATUS.has(response.status) && attempt < this.maxRetries) {
+          if (RETRY_STATUS.has(response.status) && attempt < maxRetries) {
             lastError = error;
             await sleep(retryDelay(attempt, retryAfter));
             continue;
@@ -313,7 +317,7 @@ var HttpClient = class {
         if (options.rawResponse) return response;
         return await response.json();
       } catch (err) {
-        clearTimeout(timer);
+        options.signal?.throwIfAborted();
         if (err instanceof MiosaError) {
           throw err;
         }
@@ -327,7 +331,7 @@ var HttpClient = class {
             `Network error reaching ${path}: ${err.message}`,
             err
           );
-          if (attempt < this.maxRetries) {
+          if (attempt < maxRetries) {
             lastError = networkErr;
             await sleep(retryDelay(attempt, null));
             continue;
@@ -335,6 +339,9 @@ var HttpClient = class {
           throw networkErr;
         }
         throw err;
+      } finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", cancel);
       }
     }
     throw lastError ?? new MiosaError(
@@ -394,44 +401,52 @@ var HttpClient = class {
       headers = { ...headers, "Content-Type": "application/json" };
       body5 = JSON.stringify(options.body);
     }
+    options.signal?.throwIfAborted();
     const controller = new AbortController();
-    let response;
+    const cancel = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    const deadline = options.timeout === void 0 ? void 0 : new TimeoutError(
+      `Stream ${path} timed out after ${options.timeout}ms`
+    );
+    const timer = deadline === void 0 ? void 0 : setTimeout(() => controller.abort(deadline), options.timeout);
+    let reader;
     try {
-      response = await fetch(`${this.baseUrl}${path}`, {
-        method,
-        headers,
-        body: body5,
-        signal: controller.signal
-      });
-    } catch (err) {
-      if (err instanceof TypeError) {
-        throw new NetworkError(
-          `Network error opening SSE stream: ${err.message}`,
-          err
+      let response;
+      try {
+        response = await fetch(this.buildUrl(path), {
+          method,
+          headers,
+          body: body5,
+          signal: controller.signal
+        });
+      } catch (err) {
+        if (err instanceof TypeError) {
+          throw new NetworkError(
+            `Network error opening SSE stream: ${err.message}`,
+            err
+          );
+        }
+        throw err;
+      }
+      if (!response.ok) {
+        let errorBody = {};
+        try {
+          errorBody = await response.json();
+        } catch {
+        }
+        throw MiosaError.fromResponse(
+          response.status,
+          errorBody,
+          response.headers.get("x-request-id") ?? void 0
         );
       }
-      throw err;
-    }
-    if (!response.ok) {
-      let errorBody = {};
-      try {
-        errorBody = await response.json();
-      } catch {
+      if (!response.body) {
+        throw new MiosaError("SSE stream has no body", 0, "NO_STREAM_BODY");
       }
-      throw MiosaError.fromResponse(
-        response.status,
-        errorBody,
-        response.headers.get("x-request-id") ?? void 0
-      );
-    }
-    if (!response.body) {
-      throw new MiosaError("SSE stream has no body", 0, "NO_STREAM_BODY");
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let event = null;
-    try {
+      reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let event = null;
       while (true) {
         const { done, value } = await reader.read();
         if (done) break;
@@ -459,9 +474,17 @@ var HttpClient = class {
           }
         }
       }
+    } catch (err) {
+      options.signal?.throwIfAborted();
+      if (deadline !== void 0 && controller.signal.reason === deadline) {
+        throw deadline;
+      }
+      throw err;
     } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", cancel);
       controller.abort();
-      reader.releaseLock();
+      reader?.releaseLock();
     }
   }
   /**
@@ -8494,6 +8517,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 },
@@ -8628,6 +8652,16 @@ 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) {
+  const seconds = options?.timeout ?? options?.timeoutSec ?? options?.timeout_sec;
+  if (seconds === void 0) return {};
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 86400) {
+    throw new RangeError(
+      "Exec timeout must be greater than zero and at most 86400 seconds"
+    );
+  }
+  return { timeout: seconds * 1e3 + 5e3 };
+}
 function execBody(command, options = {}) {
   return stripUndefined26({
     command,
@@ -9087,10 +9121,17 @@ var Sandbox = class _Sandbox {
   }
   async runExec(command, options) {
     this.assertRunning("exec");
+    if (options?.signal) return this.runCancellableExec(command, options);
     const response = unwrap48(
-      await this.http.post(
+      await this.http.request(
         `/sandboxes/${this.id}/exec`,
-        execBody(command, options)
+        {
+          method: "POST",
+          body: execBody(command, options),
+          signal: options?.signal,
+          maxRetries: 0,
+          ...execDeadline(options)
+        }
       )
     );
     const exitCode = Number(response.exit_code ?? response.exitCode ?? 0);
@@ -9106,13 +9147,42 @@ var Sandbox = class _Sandbox {
     }
     return result;
   }
+  async runCancellableExec(command, options) {
+    let stdout = "";
+    let stderr = "";
+    let exitCode;
+    for await (const event of this.execStream(command, options)) {
+      if (event.type === "stdout" && typeof event.line === "string")
+        stdout += event.line;
+      if (event.type === "stderr" && typeof event.line === "string")
+        stderr += event.line;
+      if (event.type === "exit" && typeof event.exit_code === "number") {
+        exitCode = event.exit_code;
+        break;
+      }
+    }
+    options.signal?.throwIfAborted();
+    if (exitCode === void 0) {
+      throw new MiosaError(
+        "Execution stream ended without a terminal result",
+        502,
+        "EXEC_STREAM_INCOMPLETE",
+        void 0,
+        void 0,
+        false
+      );
+    }
+    return { stdout, stderr, exitCode, exit_code: exitCode };
+  }
   execStream(command, options) {
     this.assertRunning("exec.stream");
     const frames = this.http.streamFrames(
       `/sandboxes/${this.id}/exec/stream`,
       {
         method: "POST",
-        body: execBody(command, options)
+        body: execBody(command, options),
+        signal: options?.signal,
+        ...execDeadline(options)
       }
     );
     return (async function* () {
@@ -9496,47 +9566,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();
@@ -9600,9 +9689,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}`,
@@ -9614,7 +9719,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;
@@ -9635,6 +9740,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");
             }
           }
         }
@@ -9645,7 +9751,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);
@@ -9656,12 +9765,21 @@ var Sandbox = class _Sandbox {
     }
   }
   async destroy() {
-    if (this.data.state === "destroyed") return;
-    await this.http.delete(`/sandboxes/${this.id}`);
+    if (this.data.state === "destroyed" || this.data.state === "destroying") {
+      return;
+    }
+    const receipt = unwrap48(
+      await this.http.delete(
+        `/sandboxes/${this.id}`
+      )
+    ) ?? {};
+    const settled = receipt.state === "destroyed" || receipt.state === void 0 && receipt.operation_id == null;
     this.data = {
       ...this.data,
-      state: "destroyed",
-      destroyed_at: (/* @__PURE__ */ new Date()).toISOString()
+      state: settled ? "destroyed" : "destroying",
+      ready: false,
+      operation_id: receipt.operation_id ?? this.data.operation_id ?? null,
+      destroyed_at: receipt.destroyed_at ?? this.data.destroyed_at ?? null
     };
   }
   delete() {