@computesdk/platform 0.0.0-stage → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,888 @@
+// src/provider.ts
+import { randomUUID } from "crypto";
+import { defineProvider } from "@computesdk/provider";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://platform.computesdk.com";
+var SDK_VERSION = "0.1.0";
+var MARKET_CODES = /* @__PURE__ */ new Set([
+  "market_cap_required",
+  "market_access_required",
+  "limit_not_met",
+  "above_protection_limit",
+  "insufficient_credits",
+  "no_market_capacity",
+  "no_provider_configured",
+  "market_lane_not_approved"
+]);
+var PlatformApiError = class extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "PlatformApiError";
+    const details = errorDetails(body);
+    const bodyCode = body && typeof body === "object" && "code" in body && typeof body.code === "string" ? body.code : void 0;
+    this.details = details;
+    this.code = (details && typeof details.code === "string" ? details.code : void 0) ?? bodyCode ?? codeForStatus(status);
+    this.retryable = !MARKET_CODES.has(this.code) && (status === 429 || status === 502 || status === 503 || status === 504);
+  }
+};
+var PlatformClientError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PlatformClientError";
+  }
+};
+function codeForStatus(status) {
+  switch (status) {
+    case 400:
+      return "bad_request";
+    case 401:
+      return "unauthenticated";
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not_found";
+    case 409:
+      return "conflict";
+    case 413:
+      return "payload_too_large";
+    case 429:
+      return "rate_limited";
+    default:
+      return status >= 500 ? "server_error" : "http_error";
+  }
+}
+function errorDetails(body) {
+  if (body && typeof body === "object" && "details" in body) {
+    const details = body.details;
+    if (details && typeof details === "object" && !Array.isArray(details)) {
+      return details;
+    }
+  }
+  return void 0;
+}
+function toErrorEnvelope(error) {
+  if (error instanceof PlatformApiError) {
+    const details = errorDetails(error.body);
+    return {
+      ok: false,
+      error: {
+        code: error.code,
+        message: error.message,
+        httpStatus: error.status,
+        retryable: error.retryable,
+        ...details !== void 0 && { details }
+      }
+    };
+  }
+  if (error instanceof PlatformClientError) {
+    return { ok: false, error: { code: error.code, message: error.message, retryable: false } };
+  }
+  if (error instanceof TypeError && /fetch failed/i.test(error.message)) {
+    const cause = error.cause;
+    const detail = cause instanceof Error ? `: ${cause.message}` : "";
+    return {
+      ok: false,
+      error: { code: "network", message: `${error.message}${detail}`, retryable: true }
+    };
+  }
+  return {
+    ok: false,
+    error: {
+      code: "unknown",
+      message: error instanceof Error ? error.message : String(error),
+      retryable: false
+    }
+  };
+}
+var PlatformClient = class {
+  constructor(auth, fetchImpl = fetch) {
+    this.auth = auth;
+    this.fetchImpl = fetchImpl;
+  }
+  get baseUrl() {
+    return this.auth.baseUrl;
+  }
+  async get(path, params, opts) {
+    const url = new URL(`${this.auth.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params ?? {})) {
+      if (value === void 0) continue;
+      for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, v);
+    }
+    const res = await this.fetchImpl(url, { headers: this.headers(), signal: opts?.signal });
+    return this.parse(res);
+  }
+  async post(path, body = {}, opts) {
+    const res = await this.fetchImpl(`${this.auth.baseUrl}${path}`, {
+      method: "POST",
+      headers: { ...this.headers(), "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: opts?.signal
+    });
+    return this.parse(res);
+  }
+  /**
+   * POST JSON and return the raw response body for SSE reading
+   * (Accept: text/event-stream). Callers feed it to `readSseNamedEvents`.
+   */
+  async postStream(path, body = {}, opts) {
+    const res = await this.fetchImpl(`${this.auth.baseUrl}${path}`, {
+      method: "POST",
+      headers: { ...this.headers(), "content-type": "application/json", accept: "text/event-stream" },
+      body: JSON.stringify(body),
+      signal: opts?.signal
+    });
+    if (!res.ok) {
+      await this.parse(res);
+    }
+    if (!res.body) throw new PlatformClientError("stream_ended", "SSE response has no body");
+    return res.body;
+  }
+  /** POST a raw text body (e.g. a unified diff to `/api/v1/actions/patches`). */
+  async postText(path, body, contentType, opts) {
+    const res = await this.fetchImpl(`${this.auth.baseUrl}${path}`, {
+      method: "POST",
+      headers: { ...this.headers(), "content-type": contentType },
+      body,
+      signal: opts?.signal
+    });
+    return this.parse(res);
+  }
+  async put(path, body = {}, opts) {
+    const res = await this.fetchImpl(`${this.auth.baseUrl}${path}`, {
+      method: "PUT",
+      headers: { ...this.headers(), "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: opts?.signal
+    });
+    return this.parse(res);
+  }
+  async patch(path, body = {}, opts) {
+    const res = await this.fetchImpl(`${this.auth.baseUrl}${path}`, {
+      method: "PATCH",
+      headers: { ...this.headers(), "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: opts?.signal
+    });
+    return this.parse(res);
+  }
+  async del(path, opts) {
+    const res = await this.fetchImpl(`${this.auth.baseUrl}${path}`, {
+      method: "DELETE",
+      headers: this.headers(),
+      signal: opts?.signal
+    });
+    return this.parse(res);
+  }
+  /**
+   * One `data:` JSON payload per SSE event. `next()` resolves to the payload,
+   * or null when the stream ends. Call `close()` to abort.
+   */
+  async *sse(path, params, opts) {
+    const url = new URL(`${this.auth.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params ?? {})) {
+      if (value === void 0) continue;
+      for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, v);
+    }
+    const res = await this.fetchImpl(url, {
+      headers: { ...this.headers(), accept: "text/event-stream" },
+      signal: opts?.signal
+    });
+    if (!res.ok) {
+      await this.parse(res);
+    }
+    if (!res.body) throw new Error("SSE response has no body");
+    yield* readSseEvents(res.body);
+  }
+  /**
+   * `sse()` with the frame's `event:` name preserved — for streams whose
+   * events are distinguished by name rather than payload shape (process
+   * follow: stdout/stderr share a `{chunk}` payload).
+   */
+  async *sseNamed(path, params, opts) {
+    const url = new URL(`${this.auth.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params ?? {})) {
+      if (value === void 0) continue;
+      for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, v);
+    }
+    const res = await this.fetchImpl(url, {
+      headers: { ...this.headers(), accept: "text/event-stream" },
+      signal: opts?.signal
+    });
+    if (!res.ok) {
+      await this.parse(res);
+    }
+    if (!res.body) throw new Error("SSE response has no body");
+    yield* readSseNamedEvents(res.body);
+  }
+  /** Download bytes following redirects (artifact URLs 302 to storage). */
+  async download(path, opts) {
+    let url = `${this.auth.baseUrl}${path}`;
+    let res = await this.fetchImpl(url, {
+      headers: this.headers(),
+      redirect: "manual",
+      signal: opts?.signal
+    });
+    const baseOrigin = new URL(this.auth.baseUrl).origin;
+    for (let hops = 0; hops < 5 && res.status >= 300 && res.status < 400; hops += 1) {
+      const location = res.headers.get("location");
+      if (!location) break;
+      const target = new URL(location, url);
+      const sameOrigin = target.origin === baseOrigin;
+      res = await this.fetchImpl(target, {
+        headers: sameOrigin ? this.headers() : { accept: "*/*" },
+        redirect: "manual",
+        signal: opts?.signal
+      });
+      url = target.toString();
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => void 0);
+      throw apiError(res, body);
+    }
+    return new Uint8Array(await res.arrayBuffer());
+  }
+  headers() {
+    const headers = {
+      authorization: `Bearer ${this.auth.apiKey}`,
+      accept: "application/json",
+      "user-agent": `@computesdk/platform/${SDK_VERSION}`
+    };
+    if (this.auth.orgSlug) headers["X-Org-Slug"] = this.auth.orgSlug;
+    return headers;
+  }
+  async parse(res) {
+    const body = await res.json().catch(() => void 0);
+    if (!res.ok) throw apiError(res, body);
+    return body;
+  }
+};
+function apiError(res, body) {
+  const error = new PlatformApiError(res.status, errorMessage(body, res.status), body);
+  const retryAfter = res.headers.get("retry-after");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    error.retryAfterMs = Number.isFinite(seconds) ? seconds * 1e3 : Math.max(0, new Date(retryAfter).getTime() - Date.now());
+  }
+  return error;
+}
+function errorMessage(body, status) {
+  let message;
+  if (body && typeof body === "object" && "error" in body && typeof body.error === "string") {
+    message = body.error;
+  } else {
+    message = `Request failed with status ${status}`;
+  }
+  if (message.includes("insufficient_scope") || typeof body === "object" && body !== null && JSON.stringify(body).includes("insufficient_scope")) {
+    message += " \u2014 run `compute login` to sign in again.";
+  }
+  const requestId = body && typeof body === "object" && "requestId" in body && typeof body.requestId === "string" ? body.requestId : void 0;
+  if (requestId) message += ` (requestId: ${requestId})`;
+  return message;
+}
+async function* readSseEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n\n")) !== -1) {
+        const event = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        for (const line of event.split("\n")) {
+          if (line.startsWith("data: ")) {
+            yield JSON.parse(line.slice(6));
+          }
+        }
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+    reader.releaseLock();
+  }
+}
+async function* readSseNamedEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n\n")) !== -1) {
+        const frame = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        let event = "message";
+        const dataLines = [];
+        for (const line of frame.split("\n")) {
+          if (line.startsWith("event: ")) event = line.slice(7);
+          else if (line.startsWith("data: ")) dataLines.push(line.slice(6));
+        }
+        if (dataLines.length > 0) {
+          yield { event, data: JSON.parse(dataLines.join("\n")) };
+        }
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+    reader.releaseLock();
+  }
+}
+var NO_CREDENTIALS_HINT = "Set COMPUTE_API_KEY, pass apiKey, or run `compute login`.";
+async function resolvePlatformAuth(opts, resolveStored = resolveStoredPlatformAuth, credentialsHint = NO_CREDENTIALS_HINT) {
+  const baseUrl = (opts.baseUrl || process.env.COMPUTE_PLATFORM_URL || process.env.BENCHMARKS_PLATFORM_URL || // legacy name
+  DEFAULT_BASE_URL).replace(/\/+$/, "");
+  let orgSlug = opts.org || process.env.COMPUTE_ORG || void 0;
+  if (!opts.allowUntrustedHost && !isTrustedPlatformHost(baseUrl)) {
+    throw new PlatformClientError(
+      "untrusted_host",
+      `Refusing to send the API key to ${baseUrl} \u2014 it is not a computesdk.com or localhost host. If this is a self-hosted/dev deployment you trust, pass --allow-untrusted-host.`
+    );
+  }
+  if (!isSecurePlatformTransport(baseUrl)) {
+    throw new PlatformClientError(
+      "insecure_transport",
+      `Refusing to send the API key over plaintext HTTP to ${baseUrl}. Use an https:// base URL; http:// is only allowed for localhost/loopback.`
+    );
+  }
+  let apiKey = opts.apiKey || process.env.COMPUTE_API_KEY || process.env.BENCHMARKS_PLATFORM_API_KEY || // legacy name
+  void 0;
+  if (!apiKey) {
+    if (!isTrustedPlatformHost(baseUrl)) {
+      throw new PlatformClientError(
+        "untrusted_host_stored_auth",
+        `Refusing to use stored platform credentials with untrusted host ${baseUrl}. Pass --api-key or set COMPUTE_API_KEY to use an explicit key with --allow-untrusted-host.`
+      );
+    }
+    let stored;
+    try {
+      stored = await resolveStored({ baseUrl });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      const detail = reason.startsWith("No credentials found") ? "No API key." : reason;
+      throw new PlatformClientError("no_credentials", `${detail} ${credentialsHint}`);
+    }
+    apiKey = stored.apiKey || stored.token || void 0;
+  }
+  if (!apiKey) {
+    throw new PlatformClientError("no_credentials", `No API key. ${credentialsHint}`);
+  }
+  return { apiKey, baseUrl, ...orgSlug && { orgSlug } };
+}
+async function resolveStoredPlatformAuth(opts) {
+  const { resolveAuth } = await import("@benchsdk/cli");
+  const auth = await resolveAuth({ baseUrl: opts.baseUrl });
+  return { apiKey: auth.apiKey, token: auth.token, orgSlug: auth.orgSlug, orgId: auth.orgId };
+}
+function isLoopbackHost(host) {
+  return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+}
+function isSecurePlatformTransport(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:") return true;
+  return url.protocol === "http:" && isLoopbackHost(url.hostname);
+}
+function isTrustedPlatformHost(baseUrl) {
+  let host;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    return false;
+  }
+  return host === "computesdk.com" || host.endsWith(".computesdk.com") || isLoopbackHost(host);
+}
+
+// src/provider.ts
+var SANDBOXES = "/api/v1/sandboxes";
+var CREATE_REQUEST_TIMEOUT_MS = 31e4;
+var CREATE_DEADLINE_MS = 6 * 6e4;
+var CREATE_POLL_MS = 2e3;
+var BOOTING_RETRY_WINDOW_MS = 6e4;
+var COMMAND_TIMEOUT_LIMIT_MS = 29e4;
+var COMMAND_LENGTH_LIMIT_BYTES = 64 * 1024;
+var FILE_CONTENT_LIMIT_BYTES = 4 * 1024 * 1024;
+var FILE_LIMIT_MESSAGE = "The files API carries about 4 MB per request. Files larger than that need an upload/download URL (not yet implemented).";
+var COMMAND_TIMEOUT_MESSAGE = "Commands over 290s can't run in one request; use background: true or processes";
+function invalidArgument(message) {
+  return new PlatformClientError("invalid_argument", message);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isNetworkError(error) {
+  return error instanceof TypeError && /fetch failed/i.test(error.message);
+}
+function isTimeoutError(error) {
+  return error instanceof DOMException && error.name === "TimeoutError";
+}
+function createSignal(timeoutMs, caller) {
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new DOMException("The create request timed out", "TimeoutError")),
+    timeoutMs
+  );
+  timer.unref?.();
+  caller?.addEventListener("abort", () => controller.abort(caller.reason), { once: true });
+  return controller.signal;
+}
+async function request(call, retryOnNetworkError) {
+  const bootingDeadline = Date.now() + BOOTING_RETRY_WINDOW_MS;
+  let bootBackoff = 500;
+  let rateLimited = 0;
+  let networkAttempts = 0;
+  for (; ; ) {
+    try {
+      return await call();
+    } catch (error) {
+      if (error instanceof PlatformApiError && error.code === "sandbox_booting" && Date.now() < bootingDeadline) {
+        await sleep(bootBackoff);
+        bootBackoff = Math.min(bootBackoff * 2, 8e3);
+        continue;
+      }
+      if (error instanceof PlatformApiError && error.status === 429 && rateLimited < 3) {
+        rateLimited += 1;
+        await sleep(error.retryAfterMs ?? Math.min(2e3 * rateLimited, 1e4));
+        continue;
+      }
+      if (isNetworkError(error) && retryOnNetworkError && networkAttempts < 2) {
+        networkAttempts += 1;
+        await sleep(500 * (networkAttempts + 1));
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+var RESOURCE_ALIASES = {
+  cpus: "cpus",
+  vcpus: "cpus",
+  memoryMb: "memoryMb",
+  memoryMiB: "memoryMb",
+  memMiB: "memoryMb",
+  memory: "memoryMb",
+  diskMb: "ephemeralDiskMb",
+  diskMiB: "ephemeralDiskMb"
+};
+var KNOWN_CREATE_KEYS = /* @__PURE__ */ new Set([
+  "size",
+  "maxPrice",
+  "orderType",
+  "providerOrder",
+  "secrets",
+  "disk",
+  "label",
+  "idempotencyKey",
+  "timeout",
+  "image",
+  "templateId",
+  "snapshotId",
+  "name",
+  "envs",
+  "signal",
+  "provider",
+  "kind"
+]);
+var VALID_SIZES = /* @__PURE__ */ new Set(["small", "medium", "large", "xlarge"]);
+function buildCreateBody(config, options) {
+  const opts = options ?? {};
+  if (opts.size !== void 0 && !VALID_SIZES.has(opts.size)) {
+    throw invalidArgument(`size must be one of ${[...VALID_SIZES].join("/")}`);
+  }
+  const body = {};
+  const resources = {};
+  for (const [key, value] of Object.entries(opts)) {
+    if (value === void 0 || KNOWN_CREATE_KEYS.has(key)) continue;
+    const mapped = RESOURCE_ALIASES[key];
+    if (mapped && typeof value === "number") {
+      resources[mapped] = value;
+    } else if (!mapped) {
+      throw invalidArgument("The platform provider supports size, or cpus/memoryMb/diskMb");
+    }
+  }
+  const hasResources = Object.keys(resources).length > 0;
+  const size = opts.size ?? (hasResources ? void 0 : config.defaults?.size);
+  if (size && hasResources) {
+    throw invalidArgument("size and resources are mutually exclusive: pass one or the other");
+  }
+  if (size) body.size = size;
+  if (hasResources) body.resources = resources;
+  const maxPrice = opts.maxPrice ?? config.defaults?.maxPrice;
+  if (maxPrice) body.maxPrice = maxPrice;
+  const orderType = opts.orderType ?? config.defaults?.orderType;
+  if (orderType) body.orderType = orderType;
+  const providerOrder = opts.providerOrder ?? config.defaults?.providerOrder;
+  if (providerOrder) body.providerOrder = providerOrder;
+  if (opts.timeout !== void 0) body.timeoutMs = opts.timeout;
+  const image = opts.image ?? opts.templateId;
+  if (image !== void 0) body.image = image;
+  if (opts.snapshotId !== void 0) body.snapshotId = opts.snapshotId;
+  const label = opts.label ?? opts.name;
+  if (label !== void 0) body.label = label;
+  if (opts.secrets !== void 0) body.secrets = opts.secrets;
+  if (opts.disk !== void 0) body.disk = opts.disk;
+  body.idempotencyKey = opts.idempotencyKey ?? `sdk-create:${randomUUID()}`;
+  return body;
+}
+function toInstance(detail, client, envs, createTimeout) {
+  return { id: detail.id, detail, client, envs: envs ?? {}, createTimeout };
+}
+function toInfo(detail, createTimeout) {
+  const status = detail.status === "destroyed" ? detail.destroyError ? "error" : "stopped" : "running";
+  return {
+    id: detail.id,
+    provider: "platform",
+    status,
+    createdAt: new Date(detail.createdAt),
+    timeout: detail.timeoutMs ?? createTimeout ?? 0,
+    metadata: {
+      provider: detail.provider,
+      providerSandboxId: detail.providerSandboxId,
+      platformStatus: detail.status,
+      placement: detail.placement,
+      cost: detail.cost,
+      label: detail.label,
+      image: detail.image,
+      secrets: detail.secrets
+    }
+  };
+}
+function checkCommandLength(command) {
+  if (new TextEncoder().encode(command).length > COMMAND_LENGTH_LIMIT_BYTES) {
+    throw invalidArgument(`Commands are limited to ${COMMAND_LENGTH_LIMIT_BYTES / 1024} KB on the platform`);
+  }
+}
+function commandBody(inst, command, options) {
+  checkCommandLength(command);
+  const body = { command };
+  if (options?.timeout !== void 0) {
+    if (options.timeout > COMMAND_TIMEOUT_LIMIT_MS) throw invalidArgument(COMMAND_TIMEOUT_MESSAGE);
+    body.timeoutMs = options.timeout;
+  }
+  if (options?.cwd !== void 0) body.cwd = options.cwd;
+  const env = { ...inst.envs, ...options?.env ?? {} };
+  if (Object.keys(env).length > 0) body.env = env;
+  return body;
+}
+var platform = defineProvider({
+  name: "platform",
+  methods: {
+    instances: {
+      create: async (config, options) => {
+        const client = await resolveClient(config);
+        const body = buildCreateBody(config, options);
+        const key = body.idempotencyKey;
+        const deadline = Date.now() + CREATE_DEADLINE_MS;
+        const signal = options?.signal;
+        for (; ; ) {
+          let detail = null;
+          try {
+            const res = await client.post(
+              SANDBOXES,
+              body,
+              { signal: createSignal(CREATE_REQUEST_TIMEOUT_MS, signal) }
+            );
+            detail = res.sandbox;
+          } catch (error) {
+            if (signal?.aborted) throw signal.reason ?? error;
+            if (isNetworkError(error) || isTimeoutError(error)) {
+              if (Date.now() < deadline) continue;
+              throw outcomeUnknown(key);
+            }
+            throw error;
+          }
+          if (detail.status === "running") {
+            return { instance: toInstance(detail, client, options?.envs, options?.timeout), instanceId: detail.id };
+          }
+          if (detail.status !== "creating") {
+            return { instance: toInstance(detail, client, options?.envs, options?.timeout), instanceId: detail.id };
+          }
+          while (Date.now() < deadline) {
+            let current;
+            try {
+              const res = await client.get(
+                `${SANDBOXES}/${detail.id}`,
+                void 0,
+                { signal }
+              );
+              current = res.sandbox;
+            } catch (error) {
+              if (signal?.aborted) throw signal.reason ?? error;
+              if (error instanceof PlatformApiError && error.status === 404) {
+                current = null;
+              } else if (isNetworkError(error) || error instanceof PlatformApiError && (error.retryable || error.status >= 500 && !MARKET_CODES.has(error.code))) {
+                const retryAfter = error instanceof PlatformApiError ? error.retryAfterMs ?? 0 : 0;
+                await sleep(Math.max(CREATE_POLL_MS, retryAfter));
+                continue;
+              } else {
+                error.fallback = false;
+                throw error;
+              }
+            }
+            if (current === null) break;
+            if (current.status === "running") {
+              return { instance: toInstance(current, client, options?.envs, options?.timeout), instanceId: current.id };
+            }
+            detail = current;
+            await sleep(CREATE_POLL_MS);
+          }
+          if (Date.now() >= deadline) throw outcomeUnknown(key);
+        }
+      },
+      getById: async (config, instanceId) => {
+        const client = await resolveClient(config);
+        try {
+          const res = await request(
+            () => client.get(`${SANDBOXES}/${instanceId}`),
+            true
+          );
+          return { instance: toInstance(res.sandbox, client), instanceId: res.sandbox.id };
+        } catch (error) {
+          if (error instanceof PlatformApiError && error.status === 404) return null;
+          throw error;
+        }
+      },
+      list: async (config) => {
+        const client = await resolveClient(config);
+        const instances = [];
+        let cursor = null;
+        do {
+          const res = await request(
+            () => client.get(SANDBOXES, {
+              status: "running",
+              limit: "100",
+              ...cursor ? { cursor } : {}
+            }),
+            true
+          );
+          for (const summary of res.sandboxes) {
+            const detail = summary;
+            instances.push({ instance: toInstance(detail, client), instanceId: summary.id });
+          }
+          cursor = res.nextCursor;
+        } while (cursor);
+        return instances;
+      },
+      destroy: async (config, instanceId) => {
+        const client = await resolveClient(config);
+        try {
+          await request(() => client.del(`${SANDBOXES}/${instanceId}`), true);
+        } catch (error) {
+          if (!(error instanceof PlatformApiError && error.status === 404)) throw error;
+        }
+      },
+      runCommand: async (inst, command, options) => {
+        if (options?.background) {
+          checkCommandLength(command);
+          await request(
+            () => inst.client.post(`${SANDBOXES}/${inst.id}/processes`, {
+              command,
+              ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+              ...Object.keys({ ...inst.envs, ...options.env ?? {} }).length > 0 ? { env: { ...inst.envs, ...options.env ?? {} } } : {}
+            }),
+            false
+          );
+          return { stdout: "", stderr: "", exitCode: 0, durationMs: 0 };
+        }
+        const res = await request(
+          () => inst.client.post(`${SANDBOXES}/${inst.id}/commands`, commandBody(inst, command, options)),
+          false
+        );
+        return { stdout: res.stdout, stderr: res.stderr, exitCode: res.exitCode, durationMs: res.durationMs };
+      },
+      streamCommand: async (inst, command, options) => {
+        const body = await request(
+          () => inst.client.postStream(`${SANDBOXES}/${inst.id}/commands`, commandBody(inst, command, options)),
+          false
+        );
+        let stdout = "";
+        let stderr = "";
+        for await (const { event, data } of readSseNamedEvents(body)) {
+          const d = data;
+          if (event === "stdout") {
+            stdout += String(d.chunk ?? "");
+            options.onStdout?.(String(d.chunk ?? ""));
+          } else if (event === "stderr") {
+            stderr += String(d.chunk ?? "");
+            options.onStderr?.(String(d.chunk ?? ""));
+          } else if (event === "exit") {
+            return {
+              stdout,
+              stderr,
+              // Killed by a signal → 128, as the CLI's followProcess does.
+              exitCode: typeof d.exitCode === "number" ? d.exitCode : 128,
+              durationMs: typeof d.durationMs === "number" ? d.durationMs : 0
+            };
+          } else if (event === "error") {
+            throw new PlatformApiError(
+              typeof d.status === "number" ? d.status : 500,
+              typeof d.error === "string" ? d.error : "Command stream failed"
+            );
+          }
+        }
+        throw new PlatformClientError("stream_ended", "Command stream ended before the command exited");
+      },
+      getInfo: async (inst) => {
+        const res = await request(
+          () => inst.client.get(`${SANDBOXES}/${inst.id}`),
+          true
+        );
+        inst.detail = res.sandbox;
+        return toInfo(res.sandbox, inst.createTimeout);
+      },
+      getUrl: async (inst, options) => {
+        try {
+          const res = await request(
+            () => inst.client.get(`${SANDBOXES}/${inst.id}/urls`, {
+              port: String(options.port),
+              ...options.protocol !== void 0 ? { protocol: options.protocol } : {}
+            }),
+            true
+          );
+          return res.url;
+        } catch (error) {
+          if (error instanceof PlatformApiError && error.status === 501) {
+            throw new Error("This sandbox's provider has no public URLs");
+          }
+          throw error;
+        }
+      },
+      filesystem: {
+        readFile: async (inst, path) => {
+          let view;
+          try {
+            view = await request(
+              () => inst.client.get(`${SANDBOXES}/${inst.id}/files`, { path }),
+              true
+            );
+          } catch (error) {
+            if (error instanceof PlatformApiError && error.status === 404) {
+              throw enoent(path);
+            }
+            if (error instanceof PlatformApiError && error.status === 413) {
+              throw invalidArgument(FILE_LIMIT_MESSAGE);
+            }
+            throw error;
+          }
+          if (view.type === "directory") {
+            throw new Error(`path is a directory: ${path}`);
+          }
+          return view.content;
+        },
+        writeFile: async (inst, path, content) => {
+          const body = { path, content };
+          if (new TextEncoder().encode(JSON.stringify(body)).length > FILE_CONTENT_LIMIT_BYTES) {
+            throw invalidArgument(FILE_LIMIT_MESSAGE);
+          }
+          await request(
+            () => inst.client.post(`${SANDBOXES}/${inst.id}/files`, body),
+            false
+          );
+        },
+        mkdir: async (inst, path) => {
+          await request(
+            () => inst.client.post(`${SANDBOXES}/${inst.id}/files`, { path, mkdir: true }),
+            false
+          );
+        },
+        readdir: async (inst, path) => {
+          let view;
+          try {
+            view = await request(
+              () => inst.client.get(`${SANDBOXES}/${inst.id}/files`, { path }),
+              true
+            );
+          } catch (error) {
+            if (error instanceof PlatformApiError && error.status === 404) throw enoent(path);
+            throw error;
+          }
+          if (view.type !== "directory") {
+            throw new Error(`path is not a directory: ${path}`);
+          }
+          return view.entries.map((e) => ({
+            name: e.name,
+            type: e.type,
+            ...e.size !== void 0 ? { size: e.size } : {},
+            ...e.modified !== void 0 ? { modified: new Date(e.modified) } : {}
+          }));
+        },
+        exists: async (inst, path) => {
+          try {
+            await request(
+              () => inst.client.get(`${SANDBOXES}/${inst.id}/files`, { path }),
+              true
+            );
+            return true;
+          } catch (error) {
+            if (error instanceof PlatformApiError && error.status === 404) return false;
+            throw error;
+          }
+        },
+        remove: async (inst, path) => {
+          await request(
+            () => inst.client.del(`${SANDBOXES}/${inst.id}/files?path=${encodeURIComponent(path)}`),
+            true
+          );
+        }
+      }
+    }
+  }
+});
+function outcomeUnknown(key) {
+  const err = new PlatformClientError(
+    "create_outcome_unknown",
+    `Sandbox create outcome unknown after 6 minutes (idempotencyKey: ${key}). Check the org dashboard before retrying \u2014 the sandbox may still be creating.`
+  );
+  err.fallback = false;
+  return err;
+}
+function enoent(path) {
+  const error = new Error(`ENOENT: no such file or directory, open '${path}'`);
+  error.code = "ENOENT";
+  return error;
+}
+var resolvedClients = /* @__PURE__ */ new WeakMap();
+function resolveClient(config) {
+  let promise = resolvedClients.get(config);
+  if (!promise) {
+    promise = resolvePlatformAuth({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      allowUntrustedHost: config.allowUntrustedHost,
+      org: config.org
+    }).then((auth) => new PlatformClient(auth, config.fetch));
+    resolvedClients.set(config, promise);
+    promise.catch(() => resolvedClients.delete(config));
+  }
+  return promise;
+}
+export {
+  DEFAULT_BASE_URL,
+  MARKET_CODES,
+  PlatformApiError,
+  PlatformClient,
+  PlatformClientError,
+  codeForStatus,
+  errorDetails,
+  isSecurePlatformTransport,
+  isTrustedPlatformHost,
+  platform,
+  readSseEvents,
+  readSseNamedEvents,
+  resolvePlatformAuth,
+  toErrorEnvelope
+};
+//# sourceMappingURL=index.mjs.map