@miosa/sdk 3.2.4 → 3.3.0

package/dist/index.js

@@ -1,5 +1,9 @@
 import { createHmac, timingSafeEqual, randomUUID } from 'crypto';
 import EventEmitter from 'events';
+import { isIP } from 'net';
+import { resolve4 } from 'dns/promises';
+import * as http2 from 'http2';
+import { createRequire } from 'module';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -18,7 +22,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 +38,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 +185,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "3.2.4";
+var SDK_VERSION = "3.3.0";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -206,15 +217,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 +303,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 +314,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 +350,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 +454,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) {
@@ -8652,16 +8670,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,
@@ -8677,7 +8708,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 ?? "");
@@ -8744,7 +8782,16 @@ var SandboxFiles = class {
     }
     return response;
   }
-  /** POST /api/v1/sandboxes/{id}/files/write-many — write multiple files atomically. */
+  /**
+   * Write a failure-atomic batch on a batch-capable guest.
+   * The guest's guarantee is whatever the response advertises: rely on it only
+   * after `atomicity === "failure_atomic"` and `read_isolation ===
+   * "file_api_operations"` compare equal, because the fields are forwarded
+   * verbatim and an older guest omits them. Never treat an unknown value or a
+   * missing field as the guarantee, and never substitute sequential writes.
+   * Shell/Docker readers may see intermediate publication; coordinate them
+   * with the write if a consistent multi-file view is required.
+   */
   async writeMany(files) {
     const http = this.sandbox.http;
     const payload = files.map((f) => ({
@@ -8819,12 +8866,54 @@ var SandboxSnapshots = class {
     return this.sandbox.deleteSnapshot(snapshotId);
   }
 };
+var MAX_TERMINAL_ARGS = 256;
+function invalidTerminalOptions(message, details) {
+  return new MiosaError(
+    message,
+    400,
+    "INVALID_TERMINAL_OPTIONS",
+    details,
+    void 0,
+    false
+  );
+}
+function assertTerminalOptions(params) {
+  if (params.shell !== void 0 && params.command !== void 0) {
+    throw invalidTerminalOptions(
+      "Terminal options cannot combine shell with command: shell names the session shell executable, command starts an executable directly",
+      { shell: params.shell, command: params.command }
+    );
+  }
+  if (params.args === void 0) return;
+  if (params.command === void 0) {
+    throw invalidTerminalOptions(
+      "Terminal options supplied args without command: arguments belong to a directly launched executable",
+      { args: params.args.length }
+    );
+  }
+  if (params.args.length > MAX_TERMINAL_ARGS) {
+    throw invalidTerminalOptions(
+      `Terminal options supplied ${params.args.length} args, at most ${MAX_TERMINAL_ARGS} are accepted`,
+      { args: params.args.length }
+    );
+  }
+  const index = params.args.findIndex(
+    (arg) => typeof arg !== "string" || arg.includes("\0")
+  );
+  if (index !== -1) {
+    throw invalidTerminalOptions(
+      `Terminal options args[${index}] is not a NUL-free string; arguments are passed to process creation literally`,
+      { index }
+    );
+  }
+}
 var SandboxTerminal = class {
   constructor(sandbox) {
     this.sandbox = sandbox;
   }
   sandbox;
   async create(params = {}) {
+    assertTerminalOptions(params);
     const body5 = Object.fromEntries(
       Object.entries(params).filter(([, v]) => v !== void 0)
     );
@@ -9145,12 +9234,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;
@@ -9158,6 +9253,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;
       }
     }
@@ -9172,7 +9268,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");
@@ -9182,7 +9284,7 @@ var Sandbox = class _Sandbox {
         method: "POST",
         body: execBody(command, options),
         signal: options?.signal,
-        ...execDeadline(options)
+        ...execStreamDeadline(options)
       }
     );
     return (async function* () {
@@ -9456,17 +9558,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 };
@@ -9805,6 +9916,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;
@@ -9900,9 +10055,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;
@@ -9912,9 +10072,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
@@ -11025,10 +11183,1101 @@ var WorkspaceMembers = class {
   }
 };
 
+// src/runner/region.ts
+var DEFAULT_RUNNER_REGION = "us";
+var KNOWN_RUNNER_REGIONS = /* @__PURE__ */ new Set();
+function regionFromApiKey(apiKey) {
+  const parts = apiKey.split("_");
+  const candidate = parts[1];
+  if (parts.length >= 3 && candidate !== void 0 && KNOWN_RUNNER_REGIONS.has(candidate)) {
+    return candidate;
+  }
+  return DEFAULT_RUNNER_REGION;
+}
+var DEFAULT_RUNNER_BASE_DOMAIN = "miosa.ai";
+function regionHostname(region, baseDomain = DEFAULT_RUNNER_BASE_DOMAIN) {
+  return `run-${region}.${baseDomain}`;
+}
+function tagHostname(region, tag, baseDomain = DEFAULT_RUNNER_BASE_DOMAIN) {
+  return `${tag}.${regionHostname(region, baseDomain)}`;
+}
+function sandboxTag(sandboxId) {
+  const first = sandboxId.charAt(0);
+  if (!first) {
+    throw new TypeError("sandboxTag: sandboxId must not be empty");
+  }
+  return first.toLowerCase();
+}
+var DnsAddressResolver = class {
+  constructor(ttlMs = 6e4) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  cache = /* @__PURE__ */ new Map();
+  async resolve(hostname) {
+    if (isIP(hostname) !== 0) return [hostname];
+    if (hostname === "localhost") return ["127.0.0.1"];
+    const cached = this.cache.get(hostname);
+    if (cached && cached.expiresAt > Date.now()) return cached.addresses;
+    const addresses = await resolve4(hostname);
+    if (addresses.length === 0) {
+      throw new Error(`DnsAddressResolver: ${hostname} resolved to zero A records`);
+    }
+    this.cache.set(hostname, { addresses, expiresAt: Date.now() + this.ttlMs });
+    return addresses;
+  }
+};
+var StaticAddressResolver = class {
+  constructor(table) {
+    this.table = table;
+  }
+  table;
+  async resolve(hostname) {
+    const addresses = this.table.get(hostname);
+    if (!addresses || addresses.length === 0) {
+      throw new Error(`StaticAddressResolver: no addresses configured for ${hostname}`);
+    }
+    return addresses;
+  }
+};
+
+// src/runner/transport.ts
+var RunnerTimeoutError = class extends Error {
+  constructor(hostname, path, timeoutMs) {
+    super(`runner request to ${hostname}${path} timed out after ${timeoutMs}ms`);
+    this.name = "RunnerTimeoutError";
+  }
+};
+var RunnerConnectError = class extends Error {
+  constructor(hostname, address, cause) {
+    super(
+      `runner transport failed to connect to ${hostname} (${address}): ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.name = "RunnerConnectError";
+  }
+};
+function isConnectFailure(error) {
+  if (error instanceof RunnerConnectError || error instanceof RunnerTimeoutError) {
+    return true;
+  }
+  if (error && typeof error === "object" && "code" in error) {
+    const code = error.code;
+    return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "ETIMEDOUT" || code === "EHOSTUNREACH" || code === "ENETUNREACH" || code === "ERR_HTTP2_GOAWAY_SESSION";
+  }
+  return false;
+}
+
+// src/runner/http2-transport.ts
+function markHandled(promise) {
+  promise.catch(() => void 0);
+  return promise;
+}
+var DEFAULT_SESSIONS_PER_ADDRESS = 8;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var Http2Transport = class {
+  protocol = "h2";
+  defaultSessionsPerAddress;
+  tls;
+  port;
+  resolver;
+  defaultTimeoutMs;
+  pools = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.defaultSessionsPerAddress = options.defaultSessionsPerAddress ?? DEFAULT_SESSIONS_PER_ADDRESS;
+    this.tls = options.tls ?? true;
+    this.port = options.port ?? (this.tls ? 443 : 80);
+    this.resolver = options.resolver ?? new DnsAddressResolver();
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  prewarm(regionHostname2, sessionsPerAddress) {
+    this.poolFor(regionHostname2, sessionsPerAddress);
+  }
+  async addressCount(regionHostname2) {
+    const addresses = await this.poolFor(regionHostname2).addresses;
+    return addresses.length;
+  }
+  async ready(regionHostname2, addressIndex) {
+    await this.acquireSession(regionHostname2, addressIndex);
+  }
+  async request(regionHostname2, addressIndex, authority, path, init) {
+    const { session } = await this.acquireSession(regionHostname2, addressIndex);
+    return this.sendRequest(regionHostname2, authority, path, session, init);
+  }
+  async streamRequest(regionHostname2, addressIndex, authority, path, init) {
+    const { session } = await this.acquireSession(regionHostname2, addressIndex);
+    return this.sendStreamRequest(authority, path, session, init);
+  }
+  /** Shared by request() and ready() - the latter just discards the session. */
+  async acquireSession(regionHostname2, addressIndex) {
+    const pool = this.poolFor(regionHostname2);
+    const addresses = await pool.addresses;
+    const n = addresses.length;
+    const addrIdx = (addressIndex % n + n) % n;
+    const address = addresses[addrIdx];
+    const groups = await pool.groups;
+    const group = groups[addrIdx];
+    if (group.length === 0) {
+      throw new Error(
+        `Http2Transport: ${regionHostname2} address ${addrIdx} has zero sessions configured (prewarm/request with sessionsPerAddress > 0 first)`
+      );
+    }
+    const cursor = pool.nextSlot.get(addrIdx) ?? 0;
+    pool.nextSlot.set(addrIdx, (cursor + 1) % group.length);
+    let session;
+    try {
+      session = await group[cursor];
+    } catch (error) {
+      throw new RunnerConnectError(regionHostname2, address, error);
+    }
+    if (session.closed || session.destroyed) {
+      const fresh = this.connectSession(regionHostname2, address);
+      group[cursor] = fresh;
+      try {
+        session = await fresh;
+      } catch (error) {
+        throw new RunnerConnectError(regionHostname2, address, error);
+      }
+    }
+    return { session };
+  }
+  async close() {
+    const pools = [...this.pools.values()];
+    this.pools.clear();
+    for (const pool of pools) {
+      const groups = await pool.groups.catch(() => []);
+      for (const group of groups) {
+        for (const slot of group) {
+          try {
+            const session = await slot;
+            if (!session.closed) session.close();
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  poolFor(regionHostname2, sessionsPerAddress) {
+    let pool = this.pools.get(regionHostname2);
+    if (!pool) {
+      pool = this.buildPool(regionHostname2, sessionsPerAddress ?? this.defaultSessionsPerAddress);
+      this.pools.set(regionHostname2, pool);
+    }
+    return pool;
+  }
+  buildPool(regionHostname2, sessionsPerAddress) {
+    const addresses = this.resolver.resolve(regionHostname2);
+    const groups = addresses.then(
+      (resolved) => resolved.map(
+        (address) => (
+          // sessionsPerAddress: 0 is a deliberate "open nothing" (e.g. a
+          // count-only probe).
+          Array.from(
+            { length: sessionsPerAddress },
+            () => markHandled(this.connectSession(regionHostname2, address))
+          )
+        )
+      )
+    );
+    markHandled(addresses);
+    markHandled(groups);
+    return { addresses, groups, nextSlot: /* @__PURE__ */ new Map() };
+  }
+  connectSession(regionHostname2, address) {
+    return new Promise((resolve, reject) => {
+      const authority = `${this.tls ? "https" : "http"}://${address}:${this.port}`;
+      const connectOptions = this.tls ? { servername: regionHostname2 } : {};
+      const session = http2.connect(authority, connectOptions);
+      const onError = (error) => {
+        session.destroy();
+        reject(error);
+      };
+      session.once("error", onError);
+      session.once("connect", () => {
+        session.removeListener("error", onError);
+        session.on("error", () => void 0);
+        resolve(session);
+      });
+    });
+  }
+  sendRequest(regionHostname2, authority, path, session, init) {
+    const timeoutMs = init.timeoutMs ?? this.defaultTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const requestHeaders = {
+        ":method": init.method,
+        ":path": path,
+        ":authority": authority,
+        ...init.headers
+      };
+      const stream = session.request(requestHeaders);
+      let status = 0;
+      const responseHeaders = {};
+      const chunks = [];
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        stream.close(http2.constants.NGHTTP2_CANCEL);
+        reject(new RunnerTimeoutError(regionHostname2, path, timeoutMs));
+      }, timeoutMs);
+      const onAbort = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        stream.close(http2.constants.NGHTTP2_CANCEL);
+        reject(new DOMException("runner request aborted", "AbortError"));
+      };
+      init.signal?.addEventListener("abort", onAbort, { once: true });
+      stream.on("response", (headers) => {
+        status = Number(headers[":status"] ?? 0);
+        for (const [key, value] of Object.entries(headers)) {
+          if (key.startsWith(":") || value === void 0) continue;
+          responseHeaders[key] = Array.isArray(value) ? value.join(", ") : String(value);
+        }
+      });
+      stream.on("data", (chunk) => chunks.push(chunk));
+      stream.on("end", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        init.signal?.removeEventListener("abort", onAbort);
+        resolve({ status, headers: responseHeaders, body: Buffer.concat(chunks).toString("utf8") });
+      });
+      stream.on("error", (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        init.signal?.removeEventListener("abort", onAbort);
+        reject(error);
+      });
+      if (init.body !== void 0) {
+        stream.end(init.body);
+      } else {
+        stream.end();
+      }
+    });
+  }
+  sendStreamRequest(authority, path, session, init) {
+    return new Promise((resolve, reject) => {
+      const requestHeaders = {
+        ":method": init.method,
+        ":path": path,
+        ":authority": authority,
+        ...init.headers
+      };
+      const stream = session.request(requestHeaders);
+      let settled = false;
+      stream.once("response", (headers) => {
+        if (settled) return;
+        settled = true;
+        const responseHeaders = {};
+        for (const [key, value] of Object.entries(headers)) {
+          if (key.startsWith(":") || value === void 0) continue;
+          responseHeaders[key] = Array.isArray(value) ? value.join(", ") : String(value);
+        }
+        resolve({
+          status: Number(headers[":status"] ?? 0),
+          headers: responseHeaders,
+          chunks: textChunks(stream)
+        });
+      });
+      stream.once("error", (error) => {
+        if (settled) return;
+        settled = true;
+        reject(error);
+      });
+      if (init.body !== void 0) {
+        stream.end(init.body);
+      } else {
+        stream.end();
+      }
+    });
+  }
+};
+async function* textChunks(stream) {
+  const decoder = new TextDecoder();
+  try {
+    for await (const chunk of stream) {
+      yield decoder.decode(chunk, { stream: true });
+    }
+  } finally {
+    if (!stream.closed) stream.close();
+  }
+}
+function markHandled2(promise) {
+  promise.catch(() => void 0);
+  return promise;
+}
+var cachedNative;
+function loadNative() {
+  if (cachedNative !== void 0) return cachedNative;
+  try {
+    const nodeRequire = createRequire(import.meta.url);
+    const candidates = ["../native/h3-runner/index.js", "../../native/h3-runner/index.js"];
+    let native = null;
+    for (const specifier of candidates) {
+      try {
+        native = nodeRequire(specifier);
+        if (native) break;
+      } catch {
+      }
+    }
+    if (!native) {
+      cachedNative = null;
+      return null;
+    }
+    cachedNative = native.available ? native : null;
+  } catch {
+    cachedNative = null;
+  }
+  return cachedNative;
+}
+function detectHttp3Support() {
+  const native = loadNative();
+  if (native) {
+    return {
+      available: true,
+      reason: `native HTTP/3 addon loaded (${native.platformArchKey()})`
+    };
+  }
+  return {
+    available: false,
+    reason: `no native HTTP/3 addon for this platform/architecture (Node ${process.version}, see native/h3-runner/README.md for which platforms are built). Falling back to HTTP/2.`
+  };
+}
+function resetHttp3DetectionCache() {
+  cachedNative = void 0;
+}
+var DEFAULT_SESSIONS_PER_ADDRESS2 = 4;
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var DEFAULT_CONNECT_TIMEOUT_MS = 2e3;
+var Http3Transport = class {
+  protocol = "h3";
+  native;
+  defaultSessionsPerAddress;
+  resolver;
+  defaultTimeoutMs;
+  connectTimeoutMs;
+  insecure;
+  port;
+  pools = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    const native = loadNative();
+    if (!native) {
+      throw new Error("Http3Transport: no native HTTP/3 addon available on this platform");
+    }
+    this.native = native;
+    this.defaultSessionsPerAddress = options.defaultSessionsPerAddress ?? DEFAULT_SESSIONS_PER_ADDRESS2;
+    this.resolver = options.resolver ?? new DnsAddressResolver();
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS2;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    this.insecure = options.insecure ?? false;
+    this.port = options.port ?? 443;
+  }
+  prewarm(regionHostname2, sessionsPerAddress) {
+    this.poolFor(regionHostname2, sessionsPerAddress);
+  }
+  async addressCount(regionHostname2) {
+    const addresses = await this.poolFor(regionHostname2).addresses;
+    return addresses.length;
+  }
+  async ready(regionHostname2, addressIndex) {
+    await this.acquireHandle(regionHostname2, addressIndex);
+  }
+  async request(regionHostname2, addressIndex, authority, path, init) {
+    const { address, handle, reconnect } = await this.acquireHandle(regionHostname2, addressIndex);
+    return this.sendRequest(regionHostname2, address, authority, path, handle, init, reconnect);
+  }
+  /**
+   * The native addon has no streaming request support yet - buffers the
+   * whole response (same as request()) and hands it back as a single
+   * chunk. Correct, not incrementally streamed; see transport.ts's doc
+   * comment on streamRequest.
+   */
+  async streamRequest(regionHostname2, addressIndex, authority, path, init) {
+    const response = await this.request(regionHostname2, addressIndex, authority, path, init);
+    return { status: response.status, headers: response.headers, chunks: singleChunk(response.body) };
+  }
+  /** Shared by request() and ready() - the latter just discards the handle. */
+  async acquireHandle(regionHostname2, addressIndex) {
+    const pool = this.poolFor(regionHostname2);
+    const addresses = await pool.addresses;
+    const n = addresses.length;
+    const addrIdx = (addressIndex % n + n) % n;
+    const address = addresses[addrIdx];
+    const groups = await pool.groups;
+    const group = groups[addrIdx];
+    if (group.length === 0) {
+      throw new Error(
+        `Http3Transport: ${regionHostname2} address ${addrIdx} has zero sessions configured (prewarm/request with sessionsPerAddress > 0 first)`
+      );
+    }
+    const cursor = pool.nextSlot.get(addrIdx) ?? 0;
+    pool.nextSlot.set(addrIdx, (cursor + 1) % group.length);
+    let handle;
+    try {
+      handle = await group[cursor];
+    } catch (error) {
+      throw new RunnerConnectError(regionHostname2, address, error);
+    }
+    const reconnect = () => {
+      const fresh = this.connectSession(regionHostname2, address);
+      group[cursor] = fresh;
+      return fresh;
+    };
+    return { address, handle, reconnect };
+  }
+  async close() {
+    const pools = [...this.pools.values()];
+    this.pools.clear();
+    for (const pool of pools) {
+      const groups = await pool.groups.catch(() => []);
+      for (const group of groups) {
+        for (const slot of group) {
+          try {
+            const handle = await slot;
+            await this.native.h3Close(handle);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  poolFor(regionHostname2, sessionsPerAddress) {
+    let pool = this.pools.get(regionHostname2);
+    if (!pool) {
+      pool = this.buildPool(regionHostname2, sessionsPerAddress ?? this.defaultSessionsPerAddress);
+      this.pools.set(regionHostname2, pool);
+    }
+    return pool;
+  }
+  buildPool(regionHostname2, sessionsPerAddress) {
+    const addresses = this.resolver.resolve(regionHostname2);
+    const groups = addresses.then(
+      (resolved) => resolved.map(
+        (address) => Array.from(
+          { length: sessionsPerAddress },
+          () => markHandled2(this.connectSession(regionHostname2, address))
+        )
+      )
+    );
+    markHandled2(addresses);
+    markHandled2(groups);
+    return { addresses, groups, nextSlot: /* @__PURE__ */ new Map() };
+  }
+  connectSession(regionHostname2, address) {
+    return this.native.h3Connect(address, regionHostname2, this.port, this.insecure, this.connectTimeoutMs);
+  }
+  async sendRequest(regionHostname2, address, authority, path, handle, init, reconnect) {
+    const timeoutMs = init.timeoutMs ?? this.defaultTimeoutMs;
+    const body5 = init.body !== void 0 ? Buffer.from(init.body) : void 0;
+    const attempt = async (activeHandle) => {
+      const requestPromise = this.native.h3Request(
+        activeHandle,
+        init.method,
+        authority,
+        path,
+        init.headers ?? {},
+        body5
+      );
+      const result = await raceWithTimeout(
+        requestPromise,
+        timeoutMs,
+        new RunnerTimeoutError(regionHostname2, path, timeoutMs)
+      );
+      return { status: result.status, headers: result.headers, body: result.body.toString("utf8") };
+    };
+    try {
+      return await attempt(handle);
+    } catch (error) {
+      let fresh;
+      try {
+        fresh = await reconnect();
+      } catch (reconnectError) {
+        throw new RunnerConnectError(regionHostname2, address, reconnectError);
+      }
+      return attempt(fresh);
+    }
+  }
+};
+function raceWithTimeout(promise, timeoutMs, timeoutError) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(timeoutError), timeoutMs);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+async function* singleChunk(body5) {
+  if (body5) yield body5;
+}
+
+// src/runner/transport-factory.ts
+function createBestTransport(options = {}) {
+  const http3 = detectHttp3Support();
+  if (!http3.available) {
+    return { transport: new Http2Transport(options.http2), http3 };
+  }
+  const transport = new RacingTransport(new Http2Transport(options.http2), new Http3Transport(options.http3));
+  return { transport, http3 };
+}
+var RacingTransport = class {
+  constructor(http22, http3) {
+    this.http2 = http22;
+    this.http3 = http3;
+  }
+  http2;
+  http3;
+  // Aspirational label for a transport that may use either protocol per
+  // host - perHostProtocol() is the ground truth once a host has decided.
+  protocol = "h3";
+  protocolByHost = /* @__PURE__ */ new Map();
+  watching = /* @__PURE__ */ new Set();
+  /** The protocol a region host is currently using - "h2" until HTTP/3 proves itself, per the class doc comment. */
+  perHostProtocol(regionHostname2) {
+    return this.protocolByHost.get(regionHostname2) ?? "h2";
+  }
+  prewarm(regionHostname2, sessionsPerAddress) {
+    this.http2.prewarm(regionHostname2, sessionsPerAddress);
+    this.http3.prewarm(regionHostname2, sessionsPerAddress);
+    this.watchHttp3(regionHostname2);
+  }
+  addressCount(regionHostname2) {
+    return this.http2.addressCount(regionHostname2);
+  }
+  async ready(regionHostname2, addressIndex) {
+    await this.transportFor(regionHostname2).ready(regionHostname2, addressIndex);
+  }
+  request(regionHostname2, addressIndex, authority, path, init) {
+    return this.transportFor(regionHostname2).request(regionHostname2, addressIndex, authority, path, init);
+  }
+  streamRequest(regionHostname2, addressIndex, authority, path, init) {
+    return this.transportFor(regionHostname2).streamRequest(regionHostname2, addressIndex, authority, path, init);
+  }
+  async close() {
+    await Promise.all([this.http2.close(), this.http3.close()]);
+  }
+  /** Whatever protocol is decided for regionHostname right now - never waits. */
+  transportFor(regionHostname2) {
+    this.watchHttp3(regionHostname2);
+    return this.perHostProtocol(regionHostname2) === "h3" ? this.http3 : this.http2;
+  }
+  /**
+   * Starts (once per host) a background wait on HTTP/3's own readiness
+   * for address 0 - connection setup, not a request - and promotes the
+   * host to "h3" the moment it resolves. Never awaited by any caller;
+   * purely a side effect that later `transportFor` calls observe.
+   */
+  watchHttp3(regionHostname2) {
+    if (this.watching.has(regionHostname2)) return;
+    this.watching.add(regionHostname2);
+    this.http3.ready(regionHostname2, 0).then(
+      () => this.protocolByHost.set(regionHostname2, "h3"),
+      () => this.protocolByHost.set(regionHostname2, "h2")
+      // failed outright - stay on HTTP/2 for this host
+    );
+  }
+};
+
+// src/runner/errors.ts
+var RunnerError = class _RunnerError extends Error {
+  status;
+  code;
+  runnerUrl;
+  /** Only meaningful for the nested "platform"/envelope shape - undefined for the flat C2 shape. */
+  retryable;
+  constructor(status, code, options = {}) {
+    super(options.message ?? `runner request failed with ${status} ${code}`);
+    this.name = "RunnerError";
+    this.status = status;
+    this.code = code;
+    this.runnerUrl = options.runnerUrl;
+    this.retryable = options.retryable;
+  }
+  static fromResponse(status, body5) {
+    let parsed = {};
+    try {
+      parsed = JSON.parse(body5);
+    } catch {
+    }
+    if (typeof parsed.error === "string") {
+      return new _RunnerError(status, parsed.error, { runnerUrl: parsed.runner_url });
+    }
+    if (parsed.error && typeof parsed.error === "object") {
+      return new _RunnerError(status, parsed.error.code || `http_${status}`, {
+        message: parsed.error.message,
+        retryable: parsed.error.retryable
+      });
+    }
+    return new _RunnerError(status, `http_${status}`);
+  }
+  get isMisdirected() {
+    return this.status === 421;
+  }
+  /**
+   * C2 (revised): admission-cap-reached ("runtime_busy") moved from 503 to
+   * 429 with `Retry-After: 0`; `feed_stale` stayed on 503. Checked by
+   * code, not status, so this stays correct regardless of which of the
+   * two carries it.
+   */
+  get isBusy() {
+    return this.code === "runtime_busy" || this.code === "feed_stale";
+  }
+  /** C2: the runner doesn't serve this create shape at all - send it to api.miosa.ai instead. */
+  get isUnsupportedRequest() {
+    return this.code === "RUNNER_UNSUPPORTED_REQUEST";
+  }
+};
+
+// src/runner/envelope.ts
+function encodeSomaBytes(content) {
+  const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) return maybeBuffer.from(bytes).toString("base64");
+  let bin = "";
+  for (const byte of bytes) bin += String.fromCharCode(byte);
+  return btoa(bin);
+}
+function decodeSomaBytes(bytes) {
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) return maybeBuffer.from(bytes.data, "base64");
+  const binary = atob(bytes.data);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function hyphenateInstanceId(instanceId) {
+  if (instanceId.length !== 32 || instanceId.includes("-")) return instanceId;
+  return [instanceId.slice(0, 8), instanceId.slice(8, 12), instanceId.slice(12, 16), instanceId.slice(16, 20), instanceId.slice(20)].join(
+    "-"
+  );
+}
+function unwrapSomaEnvelope(httpStatus, body5) {
+  let envelope = {};
+  try {
+    envelope = JSON.parse(body5 || "{}");
+  } catch {
+    throw new RunnerError(httpStatus, `http_${httpStatus}`, {
+      message: "runner response was not a valid soma.api.v1 envelope"
+    });
+  }
+  if (envelope.status === "error" || envelope.result === null || envelope.result === void 0) {
+    const detail = envelope.error;
+    throw new RunnerError(httpStatus, detail?.code || `http_${httpStatus}`, {
+      message: detail?.message,
+      retryable: detail?.retryable
+    });
+  }
+  return envelope.result;
+}
+
+// src/runner/runner-client.ts
+var DEFAULT_SESSIONS_PER_ADDRESS3 = 8;
+function createSupportedByRunner(params) {
+  const hasTemplate = params["template_id"] !== void 0 || params["templateId"] !== void 0 || params["image"] !== void 0;
+  const hasSnapshot = params["snapshot_id"] !== void 0 || params["snapshotId"] !== void 0 || params["source_snapshot_path"] !== void 0 || params["sourceSnapshotPath"] !== void 0;
+  const hasCwd = params["cwd"] !== void 0 || params["entrypoint"] !== void 0;
+  const isPersistent = params["persistent"] === true || params["always_on"] === true || params["alwaysOn"] === true;
+  const size = params["size"];
+  const isNonXs = size !== void 0 && size !== "xs";
+  return !(hasTemplate || hasSnapshot || hasCwd || isPersistent || isNonXs);
+}
+var RunnerClient = class {
+  region;
+  hostname;
+  baseDomain;
+  apiKey;
+  sessionsPerAddress;
+  transport;
+  fallbackCreate;
+  /** tag -> which of the region's resolved addresses answers for it, learned from /healthz. */
+  addressIndexByTag = /* @__PURE__ */ new Map();
+  /** sandbox id -> tag, set only once a 421 corrects the id-derived guess. */
+  correctedTag = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.region = options.region ?? regionFromApiKey(options.apiKey);
+    this.baseDomain = options.baseDomain ?? DEFAULT_RUNNER_BASE_DOMAIN;
+    this.hostname = regionHostname(this.region, this.baseDomain);
+    this.sessionsPerAddress = options.sessionsPerAddress ?? DEFAULT_SESSIONS_PER_ADDRESS3;
+    this.transport = options.transport ?? createBestTransport().transport;
+    this.fallbackCreate = options.fallbackCreate;
+    this.transport.prewarm(this.hostname, this.sessionsPerAddress);
+    void this.discoverTags();
+  }
+  get protocol() {
+    return this.transport.protocol;
+  }
+  /** The tag a 421 has corrected sandboxId to, if any. */
+  correctedTagFor(sandboxId) {
+    return this.correctedTag.get(sandboxId);
+  }
+  async healthzByIndex(addressIndex) {
+    const res = await this.transport.request(this.hostname, addressIndex, this.hostname, "/healthz", {
+      method: "GET"
+    });
+    return JSON.parse(res.body || "{}");
+  }
+  /**
+   * POST /api/v1/sandboxes against the region hostname. Create shapes the
+   * runner doesn't serve (C2) go straight to `fallbackCreate` without
+   * ever reaching the runner; a `400 RUNNER_UNSUPPORTED_REQUEST` the
+   * runner returns anyway falls back the same way, once. On `503
+   * runtime_busy`/`feed_stale` or a connect failure, retries on the next
+   * resolved IP, at most n-1 times (C6).
+   */
+  async createSandbox(params = {}, opts = {}) {
+    if (!createSupportedByRunner(params)) {
+      return this.createViaFallback(params, opts);
+    }
+    const n = await this.transport.addressCount(this.hostname);
+    if (n === 0) {
+      throw new Error(`RunnerClient: no runner addresses for ${this.hostname}`);
+    }
+    let lastError;
+    for (let attempt = 0; attempt < n; attempt++) {
+      let res;
+      try {
+        res = await this.transport.request(this.hostname, attempt, this.hostname, "/api/v1/sandboxes", {
+          method: "POST",
+          headers: this.authHeaders(opts.idempotencyKey),
+          body: JSON.stringify(params)
+        });
+      } catch (error) {
+        lastError = error;
+        continue;
+      }
+      if (res.status >= 400) {
+        const error = RunnerError.fromResponse(res.status, res.body);
+        if (error.isUnsupportedRequest) {
+          return this.createViaFallback(params, opts);
+        }
+        if (error.isBusy) {
+          lastError = error;
+          continue;
+        }
+        throw error;
+      }
+      const data = res.body ? JSON.parse(res.body) : {};
+      const runnerUrl = this.runnerUrlFrom(res, data);
+      const id = typeof data["id"] === "string" ? data["id"] : void 0;
+      if (runnerUrl !== void 0) {
+        this.addressIndexByTag.set(tagFromUrl(runnerUrl), attempt);
+      }
+      return { id: id ?? "", runnerUrl: runnerUrl ?? "", data };
+    }
+    throw lastError instanceof Error ? lastError : new Error(`RunnerClient: createSandbox exhausted every address for ${this.hostname}`);
+  }
+  async exec(sandboxId, command, opts = {}) {
+    return this.requestToSandbox(sandboxId, "POST", `/api/v1/sandboxes/${sandboxId}/exec`, {
+      command,
+      ...opts
+    });
+  }
+  /** POST /api/v1/sandboxes/{id}/exec/stream - server-sent events (C2). */
+  async *execStream(sandboxId, command, opts = {}) {
+    const streamRes = await this.sendToSandboxStream(
+      sandboxId,
+      "POST",
+      `/api/v1/sandboxes/${sandboxId}/exec/stream`,
+      { command, ...opts }
+    );
+    if (streamRes.status >= 400) {
+      let errorBody = "";
+      for await (const chunk of streamRes.chunks) errorBody += chunk;
+      throw RunnerError.fromResponse(streamRes.status, errorBody);
+    }
+    yield* parseSseEvents(streamRes.chunks);
+  }
+  /** Returns the sandbox's final usage: cpu_ms, lifetime_ms (C2). */
+  async destroySandbox(sandboxId) {
+    const result = await this.requestToSandbox(sandboxId, "DELETE", `/api/v1/sandboxes/${sandboxId}`);
+    this.correctedTag.delete(sandboxId);
+    return result;
+  }
+  // ─── C2b: per-sandbox routes (soma.api.v1 envelope) ──────────────────────
+  async get(sandboxId, opts = {}) {
+    const body5 = opts.operationId !== void 0 ? { operation_id: opts.operationId } : void 0;
+    const result = await this.requestEnvelopeToSandbox(
+      sandboxId,
+      "GET",
+      `/api/v1/sandboxes/${sandboxId}`,
+      body5
+    );
+    return { ...result, instance_id: hyphenateInstanceId(result.instance_id) };
+  }
+  async stop(sandboxId, opts = {}) {
+    const body5 = opts.operationId !== void 0 ? { operation_id: opts.operationId } : void 0;
+    const result = await this.requestEnvelopeToSandbox(
+      sandboxId,
+      "POST",
+      `/api/v1/sandboxes/${sandboxId}/stop`,
+      body5
+    );
+    return { ...result, instance_id: hyphenateInstanceId(result.instance_id) };
+  }
+  /**
+   * PATCH /api/v1/sandboxes/{id} {"timeout":seconds} - resets the idle
+   * timeout (default 300s; every call to the sandbox already resets it).
+   * Flat C2 response shape (C2b line 84), not the envelope - errors still
+   * use the platform shape (400 INVALID_PARAM, 404 NOT_FOUND), which
+   * RunnerError.fromResponse already parses either way.
+   */
+  async setTimeout(sandboxId, seconds) {
+    const result = await this.requestToSandbox(sandboxId, "PATCH", `/api/v1/sandboxes/${sandboxId}`, {
+      timeout: seconds
+    });
+    return result;
+  }
+  /**
+   * GET /api/v1/sandboxes - scoped to ONE runner host (C2b: "the calling
+   * tenant's sandboxes on this runner"), not the whole region. Defaults
+   * to address 0; pass `tag` to target the host currently known for that
+   * tag, or `addressIndex` directly.
+   */
+  async list(opts = {}) {
+    const addressIndex = opts.tag !== void 0 ? await this.resolveAddressIndexForTag(opts.tag) : opts.addressIndex ?? 0;
+    const res = await this.transport.request(this.hostname, addressIndex, this.hostname, "/api/v1/sandboxes", {
+      method: "GET",
+      headers: this.authHeaders()
+    });
+    if (res.status >= 400) throw RunnerError.fromResponse(res.status, res.body);
+    const result = unwrapSomaEnvelope(res.status, res.body);
+    return {
+      ...result,
+      sandboxes: result.sandboxes.map((entry) => ({ ...entry, instance_id: hyphenateInstanceId(entry.instance_id) }))
+    };
+  }
+  filesystem = {
+    read: (sandboxId, path) => this.filesystemOp(sandboxId, "read", { path }),
+    write: (sandboxId, path, content) => this.filesystemOp(sandboxId, "write", { path, content: encodeSomaBytes(content) }),
+    list: (sandboxId, path) => this.filesystemOp(sandboxId, "list", { path }),
+    exists: (sandboxId, path) => this.filesystemOp(sandboxId, "exists", { path }),
+    remove: (sandboxId, path, recursive) => this.filesystemOp(sandboxId, "remove", { path, ...recursive !== void 0 ? { recursive } : {} }),
+    mkdir: (sandboxId, path) => this.filesystemOp(sandboxId, "mkdir", { path }),
+    /** Decodes a read() result's base64 `content` into bytes. */
+    decode: decodeSomaBytes
+  };
+  terminal = {
+    open: (sandboxId, columns, rows) => this.terminalOp(sandboxId, "open", { columns, rows }),
+    resize: (sandboxId, columns, rows) => this.terminalOp(sandboxId, "resize", { columns, rows }),
+    write: (sandboxId, input) => this.terminalOp(sandboxId, "write", { input: encodeSomaBytes(input) }),
+    read: (sandboxId, waitMs) => this.terminalOp(sandboxId, "read", waitMs !== void 0 ? { wait_ms: waitMs } : {}),
+    close: (sandboxId) => this.terminalOp(sandboxId, "close", {}),
+    /** Decodes a read() result's base64 `output` into bytes. */
+    decode: decodeSomaBytes
+  };
+  /**
+   * Low-level escape hatch: sends method/path straight to sandboxId's
+   * runner host, with the same tag-routing, 421-follow and auth every
+   * named method above uses, parsing the response as the flat C2 shape
+   * (not the C2b envelope - use filesystem/terminal/get/stop/list, or
+   * requestEnvelope() for an un-wrapped route not named here yet).
+   */
+  request(sandboxId, method, path, body5) {
+    return this.requestToSandbox(sandboxId, method, path, body5);
+  }
+  /** Same as request(), but unwraps the response as a C2b soma.api.v1 envelope. */
+  requestEnvelope(sandboxId, method, path, body5) {
+    return this.requestEnvelopeToSandbox(sandboxId, method, path, body5);
+  }
+  async close() {
+    await this.transport.close();
+  }
+  filesystemOp(sandboxId, op, body5) {
+    return this.requestEnvelopeToSandbox(sandboxId, "POST", `/api/v1/sandboxes/${sandboxId}/filesystem/${op}`, body5);
+  }
+  terminalOp(sandboxId, op, body5) {
+    return this.requestEnvelopeToSandbox(sandboxId, "POST", `/api/v1/sandboxes/${sandboxId}/terminal/${op}`, body5);
+  }
+  async createViaFallback(params, opts) {
+    if (!this.fallbackCreate) {
+      throw new Error(
+        "RunnerClient: this create isn't served by the runner (C2) and no fallbackCreate was configured - wire RunnerClientOptions.fallbackCreate to the control-plane create path (api.miosa.ai)"
+      );
+    }
+    return this.fallbackCreate(params, opts);
+  }
+  /**
+   * Learns which resolved region address answers for which tag, via each
+   * one's own unauthenticated `/healthz` (C2) - best effort, never awaited
+   * by the constructor. A tag missed here (a host that joined after this
+   * client started, or a transient `/healthz` failure) just costs a
+   * repeat of this same probe on that sandbox's first real request,
+   * instead of none at all.
+   */
+  async discoverTags() {
+    try {
+      const n = await this.transport.addressCount(this.hostname);
+      const probes = await Promise.allSettled(
+        Array.from({ length: n }, (_, i) => this.healthzByIndex(i))
+      );
+      probes.forEach((probe, addressIndex) => {
+        if (probe.status === "fulfilled" && probe.value.tag) {
+          this.addressIndexByTag.set(probe.value.tag, addressIndex);
+        }
+      });
+    } catch {
+    }
+  }
+  /**
+   * Sends method/path to sandboxId's runner host - the id-derived tag, or
+   * a previously 421-corrected one - following a single `421 misdirected`
+   * to the `runner_url` it names (C6). A connect failure here is not
+   * retried across other hosts: a sandbox has exactly one owner. Returns
+   * the raw response; requestToSandbox/requestEnvelopeToSandbox each
+   * parse it according to their route's response shape (C2 vs C2b).
+   */
+  async sendToSandbox(sandboxId, method, path, body5) {
+    let tag = this.correctedTag.get(sandboxId) ?? sandboxTag(sandboxId);
+    let addressIndex = await this.resolveAddressIndexForTag(tag);
+    let followed = false;
+    for (; ; ) {
+      const authority = tagHostname(this.region, tag, this.baseDomain);
+      const res = await this.transport.request(this.hostname, addressIndex, authority, path, {
+        method,
+        headers: this.authHeaders(),
+        ...body5 !== void 0 ? { body: JSON.stringify(body5) } : {}
+      });
+      if (res.status === 421 && !followed) {
+        const misdirected = RunnerError.fromResponse(res.status, res.body);
+        if (misdirected.runnerUrl) {
+          tag = tagFromUrl(misdirected.runnerUrl);
+          addressIndex = await this.resolveAddressIndexForTag(tag);
+          followed = true;
+          continue;
+        }
+      }
+      if (followed) this.correctedTag.set(sandboxId, tag);
+      return res;
+    }
+  }
+  /** Same routing as sendToSandbox, for a streaming (SSE) response. */
+  async sendToSandboxStream(sandboxId, method, path, body5) {
+    let tag = this.correctedTag.get(sandboxId) ?? sandboxTag(sandboxId);
+    let addressIndex = await this.resolveAddressIndexForTag(tag);
+    let followed = false;
+    for (; ; ) {
+      const authority = tagHostname(this.region, tag, this.baseDomain);
+      const streamRes = await this.transport.streamRequest(this.hostname, addressIndex, authority, path, {
+        method,
+        headers: this.authHeaders(),
+        ...body5 !== void 0 ? { body: JSON.stringify(body5) } : {}
+      });
+      if (streamRes.status === 421 && !followed) {
+        let errorBody = "";
+        for await (const chunk of streamRes.chunks) errorBody += chunk;
+        const misdirected = RunnerError.fromResponse(streamRes.status, errorBody);
+        if (misdirected.runnerUrl) {
+          tag = tagFromUrl(misdirected.runnerUrl);
+          addressIndex = await this.resolveAddressIndexForTag(tag);
+          followed = true;
+          continue;
+        }
+        if (followed) this.correctedTag.set(sandboxId, tag);
+        return { status: streamRes.status, headers: streamRes.headers, chunks: singleChunk2(errorBody) };
+      }
+      if (followed) this.correctedTag.set(sandboxId, tag);
+      return streamRes;
+    }
+  }
+  /** C2's flat shape: parses >=400 with RunnerError, else JSON.parses the raw body. */
+  async requestToSandbox(sandboxId, method, path, body5) {
+    const res = await this.sendToSandbox(sandboxId, method, path, body5);
+    if (res.status >= 400) throw RunnerError.fromResponse(res.status, res.body);
+    return res.body ? JSON.parse(res.body) : {};
+  }
+  /**
+   * C2b's envelope shape: a >=400 response may still be the flat C2 shape
+   * (401/403/429/503/421 happen before the envelope layer) - RunnerError
+   * .fromResponse parses either, so it's used directly rather than
+   * routing through the envelope parser. Only a <400 response is
+   * unwrapped as a genuine soma.api.v1 envelope.
+   */
+  async requestEnvelopeToSandbox(sandboxId, method, path, body5) {
+    const res = await this.sendToSandbox(sandboxId, method, path, body5);
+    if (res.status >= 400) throw RunnerError.fromResponse(res.status, res.body);
+    return unwrapSomaEnvelope(res.status, res.body);
+  }
+  /**
+   * `addressIndexByTag` first; if that tag hasn't been seen yet (a host
+   * that joined after construction, or this is the very first request
+   * racing the background discovery), refreshes discovery once and falls
+   * back to address 0 as a last resort - the request itself still ends up
+   * correct either way, via a 421 follow, just one round trip slower.
+   */
+  async resolveAddressIndexForTag(tag) {
+    const known = this.addressIndexByTag.get(tag);
+    if (known !== void 0) return known;
+    await this.discoverTags();
+    return this.addressIndexByTag.get(tag) ?? 0;
+  }
+  runnerUrlFrom(res, data) {
+    const header = res.headers["soma-runner-url"];
+    if (header) return header;
+    const fromBody = data["runner_url"];
+    return typeof fromBody === "string" ? fromBody : void 0;
+  }
+  authHeaders(idempotencyKey11) {
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      "content-type": "application/json",
+      accept: "application/json"
+    };
+    if (idempotencyKey11) headers["idempotency-key"] = idempotencyKey11;
+    return headers;
+  }
+};
+function tagFromUrl(url) {
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    hostname = url;
+  }
+  return hostname.split(".")[0] ?? hostname;
+}
+async function* singleChunk2(body5) {
+  if (body5) yield body5;
+}
+async function* parseSseEvents(chunks) {
+  let buffer = "";
+  for await (const chunk of chunks) {
+    buffer += chunk;
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIdx).replace(/\r$/, "");
+      buffer = buffer.slice(newlineIdx + 1);
+      if (line.startsWith("data:")) {
+        const raw = line.slice(5).trim();
+        if (raw === "" || raw === "[DONE]") continue;
+        try {
+          yield JSON.parse(raw);
+        } catch {
+        }
+      }
+    }
+  }
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.miosa.ai/api/v1";
 var DEFAULT_TIMEOUT2 = 3e4;
 var DEFAULT_MAX_RETRIES2 = 3;
+function runnerModeFromEnv() {
+  return typeof process !== "undefined" && typeof process.env !== "undefined" && process.env["MIOSA_RUNNER_MODE"] === "1";
+}
+function runnerRegionFromEnv() {
+  if (typeof process === "undefined" || typeof process.env === "undefined") return void 0;
+  return process.env["MIOSA_RUNNER_REGION"];
+}
 var Miosa = class {
   /** Per-workspace user roster — list, add, update role, remove. */
   workspaceMembers;
@@ -11165,6 +12414,14 @@ var Miosa = class {
   network;
   /** Egress audit log — every outbound request, paginated query + tail. */
   audit;
+  /**
+   * SOMA one-hop runner path (opt-in via `config.runner.enabled` or
+   * `MIOSA_RUNNER_MODE=1`) - talks straight to `run-<region>.miosa.ai` for
+   * sandbox create/exec/destroy, bypassing the control-plane hop. `undefined`
+   * unless enabled; every other resource above is unaffected either way.
+   * See ONE-HOP-RUNNER-DESIGN-2026-10-02.md and RUNNER-CONTRACTS-2026-10-02.md.
+   */
+  runner;
   http;
   constructor(config) {
     if (config.apiKey && config.accessToken) {
@@ -11249,6 +12506,24 @@ var Miosa = class {
     this.secrets = new EgressSecrets(this.http);
     this.network = new EgressNetwork(this.http);
     this.audit = new EgressAudit(this.http);
+    const runnerEnabled = config.runner?.enabled ?? runnerModeFromEnv();
+    const runnerRegion = config.runner?.region ?? runnerRegionFromEnv();
+    this.runner = runnerEnabled ? new RunnerClient({
+      apiKey: credential,
+      ...runnerRegion ? { region: runnerRegion } : {},
+      ...config.runner?.baseDomain ? { baseDomain: config.runner.baseDomain } : {},
+      ...config.tenant ? { tenant: config.tenant } : {},
+      // C2: creates the runner doesn't serve (template/image/snapshot/
+      // cwd/persistent/non-xs) go through the existing control-plane
+      // path instead of failing outright.
+      fallbackCreate: async (params, fallbackOpts) => {
+        const sandbox = await this.sandboxes.create({
+          ...params,
+          ...fallbackOpts.idempotencyKey ? { idempotencyKey: fallbackOpts.idempotencyKey } : {}
+        });
+        return { id: sandbox.id, runnerUrl: "", data: sandbox.data };
+      }
+    }) : void 0;
   }
 };
 
@@ -11740,6 +13015,6 @@ var AppAuth = class {
   }
 };
 
-export { AGENT_BUILD_KIND_SPECS, Admin, AgentDefinitions, AgentRuntimeProfiles, Analytics, ApiKeys, AppAuth, AppDocuments, AuditLog, AuthError, Benchmarks, BuilderSessions, Channels, Checkpoints, Cloud, CommandCenter, Community, Completions, Computer, ComputerAudit, ComputerAutoStop, ComputerConnectors, ComputerEnv, ComputerInbox, ComputerLogs, ComputerNetwork, ComputerOsa, ComputerPorts, ComputerSecrets, ComputerTerminal, ComputerVolumes, Computers, Connectors, Credits, CronJobs, DEFAULT_AGENT_BUILD_OUTPUT_ROOT, DEFAULT_AGENT_BUILD_PACKET_VERSION, Dashboard, Databases, DeploymentConnectors, DeploymentDomains, DeploymentReleases, DeploymentRuntimeInstances, DeploymentVersions, Deployments, Desktop, Devices, DockerDeploy, EgressAudit, EgressHostNotAllowedError, EgressNetwork, EgressSecrets, Email, EmailCampaigns, EmailInbox, EmailTemplates, Embeddings, Exec, ExternalKeys, Files, FlatCustomDomains, Forge, ForgeContractError, ForgePolicyViolationError, ForgeRepositories, ForgeStorageError, ForgeUnavailableError, Functions, HealthChecks, InstallationRequiredError, InsufficientCreditsError, Integrations, ManagedProviderBindingOnlyError, Mcp, Miosa, MiosaError, Models, NetworkError, NetworkPolicy, NotFoundError, OAuthFlow, OpenComputers, OrgInvites, OrganizationMembers, Organizations, ProjectAuth, ProjectIntegrations, ProjectNotLinkedError, ProviderDefaults, RateLimitError, Regions, RunGroups, Runs, RuntimeCapabilitiesResource, RuntimeEnv, SANDBOX_TEMPLATE, Sandbox, SandboxAudit, SandboxCommands, SandboxConnectors, SandboxEnv, SandboxEvents, SandboxFiles, SandboxNetwork, SandboxPreview, SandboxPreviews, SandboxSecrets, SandboxTags, SandboxTemplates, SandboxTerminal, Sandboxes, ScopeNotAllowedError, ScopedFs, Settings, SnapshotsStandalone, Storage, SubjectNotAllowedError, Templates, Tenant, TimeoutError, TokenRefreshFailedError, Usage, UserAuthorizationRequiredError, ValidationError, Volumes, Webhooks, WorkspaceInvites, WorkspaceMembers, createAgentBuildExecutionPacket, createAgentBuildExpectedOutputs, createAgentBuildPrompt, createBuildRunParams, getAgentBuildKindSpec, resolveAgentBuildKind, verifySignature };
+export { AGENT_BUILD_KIND_SPECS, Admin, AgentDefinitions, AgentRuntimeProfiles, Analytics, ApiKeys, AppAuth, AppDocuments, AuditLog, AuthError, Benchmarks, BuilderSessions, Channels, Checkpoints, Cloud, CommandCenter, Community, Completions, Computer, ComputerAudit, ComputerAutoStop, ComputerConnectors, ComputerEnv, ComputerInbox, ComputerLogs, ComputerNetwork, ComputerOsa, ComputerPorts, ComputerSecrets, ComputerTerminal, ComputerVolumes, Computers, Connectors, Credits, CronJobs, DEFAULT_AGENT_BUILD_OUTPUT_ROOT, DEFAULT_AGENT_BUILD_PACKET_VERSION, Dashboard, Databases, DeploymentConnectors, DeploymentDomains, DeploymentReleases, DeploymentRuntimeInstances, DeploymentVersions, Deployments, Desktop, Devices, DnsAddressResolver, DockerDeploy, EgressAudit, EgressHostNotAllowedError, EgressNetwork, EgressSecrets, Email, EmailCampaigns, EmailInbox, EmailTemplates, Embeddings, Exec, ExternalKeys, Files, FlatCustomDomains, Forge, ForgeContractError, ForgePolicyViolationError, ForgeRepositories, ForgeStorageError, ForgeUnavailableError, Functions, HealthChecks, Http2Transport, Http3Transport, InstallationRequiredError, InsufficientCreditsError, Integrations, ManagedProviderBindingOnlyError, Mcp, Miosa, MiosaError, Models, NetworkError, NetworkPolicy, NotFoundError, OAuthFlow, OpenComputers, OrgInvites, OrganizationMembers, Organizations, ProjectAuth, ProjectIntegrations, ProjectNotLinkedError, ProviderDefaults, RacingTransport, RateLimitError, Regions, RunGroups, RunnerClient, RunnerConnectError, RunnerError, RunnerTimeoutError, Runs, RuntimeCapabilitiesResource, RuntimeEnv, SANDBOX_TEMPLATE, Sandbox, SandboxAudit, SandboxCommands, SandboxConnectors, SandboxEnv, SandboxEvents, SandboxFiles, SandboxNetwork, SandboxPreview, SandboxPreviews, SandboxSecrets, SandboxTags, SandboxTemplates, SandboxTerminal, Sandboxes, ScopeNotAllowedError, ScopedFs, Settings, SnapshotsStandalone, StaticAddressResolver, Storage, SubjectNotAllowedError, Templates, Tenant, TimeoutError, TokenRefreshFailedError, Usage, UserAuthorizationRequiredError, ValidationError, Volumes, Webhooks, WorkspaceInvites, WorkspaceMembers, createAgentBuildExecutionPacket, createAgentBuildExpectedOutputs, createAgentBuildPrompt, createBestTransport, createBuildRunParams, decodeSomaBytes, detectHttp3Support, encodeSomaBytes, getAgentBuildKindSpec, hyphenateInstanceId, isConnectFailure, regionFromApiKey, regionHostname, resetHttp3DetectionCache, resolveAgentBuildKind, sandboxTag, tagHostname, unwrapSomaEnvelope, verifySignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map