@miosa/sdk 3.2.2 → 3.2.3

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>;

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.3";
 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();
     }
   }
   /**
@@ -8628,6 +8651,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 +9120,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 +9146,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* () {
@@ -9656,12 +9725,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() {