@enclave-run/sdk 0.0.0-dev.4 → 0.0.0-dev.5

package/dist/index.js

@@ -103,9 +103,11 @@ __export(src_exports, {
   Sandbox: () => Sandbox,
   SandboxCreateRejectedError: () => SandboxCreateRejectedError,
   SandboxError: () => SandboxError,
+  SandboxRegionScope: () => SandboxRegionScope,
   Template: () => Template,
   TemplateBase: () => TemplateBase,
   TemplateError: () => TemplateError,
+  TemplateTagConflictError: () => TemplateTagConflictError,
   TimeoutError: () => TimeoutError,
   default: () => src_default,
   defaultBuildLogger: () => defaultBuildLogger,
@@ -125,7 +127,7 @@ var import_openapi_fetch = __toESM(require("openapi-fetch"));
 var import_platform2 = __toESM(require("platform"));
 
 // package.json
-var version = "0.0.0-dev.4";
+var version = "0.0.0-dev.5";
 
 // src/utils.ts
 var import_platform = __toESM(require("platform"));
@@ -309,6 +311,21 @@ var TemplateError = class extends SandboxError {
     this.name = "TemplateError";
   }
 };
+var TemplateTagConflictError = class extends TemplateError {
+  constructor(options) {
+    var _a3;
+    super(
+      (_a3 = options.message) != null ? _a3 : `Template tag "${options.tag}" conflicted with another mutation. Fetch its current head with Template.getTagHead() before retrying.`
+    );
+    this.name = "TemplateTagConflictError";
+    this.templateId = options.templateId;
+    this.tag = options.tag;
+    this.candidateBuildId = options.candidateBuildId;
+    this.expectedBuildId = options.expectedBuildId;
+    this.expectedVersion = options.expectedVersion;
+    this.reason = options.reason;
+  }
+};
 var RateLimitError = class extends SandboxError {
   constructor(message) {
     super(message);
@@ -1714,9 +1731,9 @@ var ALL_TRAFFIC = "0.0.0.0/0";
 function shellEscape(value) {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
-function withCredentials(url, username, password) {
+function withCredentials(url2, username, password) {
   if (!username && !password) {
-    return url;
+    return url2;
   }
   if (!username || !password) {
     throw new InvalidArgumentError(
@@ -1725,9 +1742,9 @@ function withCredentials(url, username, password) {
   }
   let parsed;
   try {
-    parsed = new URL(url);
+    parsed = new URL(url2);
   } catch (e) {
-    throw new InvalidArgumentError(`Invalid Git URL: ${url}`);
+    throw new InvalidArgumentError(`Invalid Git URL: ${url2}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new InvalidArgumentError(
@@ -1738,27 +1755,27 @@ function withCredentials(url, username, password) {
   parsed.password = password;
   return parsed.toString();
 }
-function stripCredentials(url) {
+function stripCredentials(url2) {
   let parsed;
   try {
-    parsed = new URL(url);
+    parsed = new URL(url2);
   } catch (e) {
-    return url;
+    return url2;
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    return url;
+    return url2;
   }
   if (!parsed.username && !parsed.password) {
-    return url;
+    return url2;
   }
   parsed.username = "";
   parsed.password = "";
   return parsed.toString();
 }
-function deriveRepoDirFromUrl(url) {
+function deriveRepoDirFromUrl(url2) {
   let parsed;
   try {
-    parsed = new URL(url);
+    parsed = new URL(url2);
   } catch (e) {
     return void 0;
   }
@@ -2045,7 +2062,7 @@ var Git = class {
    * @param opts Clone options.
    * @returns Command result from the command runner.
    */
-  async clone(url, opts) {
+  async clone(url2, opts) {
     const _a3 = opts != null ? opts : {}, {
       username,
       password,
@@ -2067,10 +2084,10 @@ var Git = class {
       );
     }
     const attemptClone = async (authUsername, authPassword) => {
-      const urlWithCreds = authUsername && authPassword ? withCredentials(url, authUsername, authPassword) : url;
+      const urlWithCreds = authUsername && authPassword ? withCredentials(url2, authUsername, authPassword) : url2;
       const sanitizedUrl = stripCredentials(urlWithCreds);
       const stripInlineCreds = !dangerouslyStoreCredentials && sanitizedUrl !== urlWithCreds;
-      const repoPath = stripInlineCreds ? path2 != null ? path2 : deriveRepoDirFromUrl(url) : path2;
+      const repoPath = stripInlineCreds ? path2 != null ? path2 : deriveRepoDirFromUrl(url2) : path2;
       if (stripInlineCreds && !repoPath) {
         throw new InvalidArgumentError(
           "A destination path is required when using credentials without storing them."
@@ -2129,8 +2146,8 @@ var Git = class {
    * @param opts Remote add options.
    * @returns Command result from the command runner.
    */
-  async remoteAdd(path2, name, url, opts) {
-    if (!name || !url) {
+  async remoteAdd(path2, name, url2, opts) {
+    if (!name || !url2) {
       throw new InvalidArgumentError(
         "Both remote name and URL are required to add a git remote."
       );
@@ -2140,12 +2157,12 @@ var Git = class {
     if (fetch2) {
       addArgs.push("-f");
     }
-    addArgs.push(name, url);
+    addArgs.push(name, url2);
     if (!overwrite) {
       return this.runGit(addArgs, path2, rest);
     }
     const addCmd = buildGitCommand(addArgs, path2);
-    const setUrlCmd = buildGitCommand(["remote", "set-url", name, url], path2);
+    const setUrlCmd = buildGitCommand(["remote", "set-url", name, url2], path2);
     let cmd = `${addCmd} || ${setUrlCmd}`;
     if (fetch2) {
       const fetchCmd = buildGitCommand(["fetch", name], path2);
@@ -2590,13 +2607,13 @@ var Git = class {
   }
   async getRemoteUrl(path2, remote, opts) {
     const result = await this.runGit(["remote", "get-url", remote], path2, opts);
-    const url = result.stdout.trim();
-    if (!url) {
+    const url2 = result.stdout.trim();
+    if (!url2) {
       throw new InvalidArgumentError(
         `Remote "${remote}" URL not found in repository.`
       );
     }
-    return url;
+    return url2;
   }
   async resolveRemoteName(path2, remote, opts) {
     if (remote) {
@@ -3121,6 +3138,26 @@ function getLifecycle(opts) {
   var _a3;
   return (_a3 = opts == null ? void 0 : opts.lifecycle) != null ? _a3 : { onTimeout: "kill", autoResume: false };
 }
+function resolveSandboxTarget(target, opts) {
+  if (typeof target === "string") {
+    return {
+      sandboxId: target,
+      config: ConnectionConfig.forSandbox(opts)
+    };
+  }
+  const referenceRegion = ConnectionConfig.resolveRegion(target.region);
+  if ((opts == null ? void 0 : opts.region) && ConnectionConfig.resolveRegion(opts.region) !== referenceRegion) {
+    throw new Error(
+      `Sandbox ${target.sandboxId} belongs to region "${referenceRegion}", not "${opts.region}"`
+    );
+  }
+  return {
+    sandboxId: target.sandboxId,
+    config: ConnectionConfig.forSandbox(__spreadProps(__spreadValues({}, opts), {
+      region: referenceRegion
+    }))
+  };
+}
 var SandboxApi = class {
   constructor() {
   }
@@ -3132,9 +3169,9 @@ var SandboxApi = class {
    *
    * @returns `true` if the sandbox was found and killed, `false` otherwise.
    */
-  static async kill(sandboxId, opts) {
+  static async kill(target, opts) {
     var _a3;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const res = await client.api.DELETE("/sandboxes/{sandboxID}", {
       params: {
@@ -3161,8 +3198,8 @@ var SandboxApi = class {
    *
    * @returns sandbox information.
    */
-  static async getInfo(sandboxId, opts) {
-    const fullInfo = await this.getFullInfo(sandboxId, opts);
+  static async getInfo(target, opts) {
+    const fullInfo = await this.getFullInfo(target, opts);
     delete fullInfo.envdAccessToken;
     delete fullInfo.sandboxDomain;
     return fullInfo;
@@ -3175,9 +3212,9 @@ var SandboxApi = class {
    *
    * @returns  List of sandbox metrics containing CPU, memory and disk usage information.
    */
-  static async getMetrics(sandboxId, opts) {
+  static async getMetrics(target, opts) {
     var _a3, _b;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const start = (opts == null ? void 0 : opts.start) ? opts.start.getTime() : void 0;
     const end = (opts == null ? void 0 : opts.end) ? opts.end.getTime() : void 0;
@@ -3220,9 +3257,9 @@ var SandboxApi = class {
    * @param timeoutMs timeout in **milliseconds**.
    * @param opts connection options.
    */
-  static async setTimeout(sandboxId, timeoutMs, opts) {
+  static async setTimeout(target, timeoutMs, opts) {
     var _a3;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const res = await client.api.POST("/sandboxes/{sandboxID}/timeout", {
       params: {
@@ -3243,9 +3280,9 @@ var SandboxApi = class {
       throw err;
     }
   }
-  static async getFullInfo(sandboxId, opts) {
+  static async getFullInfo(target, opts) {
     var _a3, _b;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const res = await client.api.GET("/sandboxes/{sandboxID}", {
       params: {
@@ -3267,6 +3304,7 @@ var SandboxApi = class {
     }
     return __spreadProps(__spreadValues({
       sandboxId: res.data.sandboxID,
+      buildId: res.data.buildID,
       templateId: res.data.templateID
     }, res.data.alias && { name: res.data.alias }), {
       metadata: (_b = res.data.metadata) != null ? _b : {},
@@ -3289,9 +3327,9 @@ var SandboxApi = class {
    *
    * @returns `true` if the sandbox got paused, `false` if the sandbox was already paused.
    */
-  static async pause(sandboxId, opts) {
+  static async pause(target, opts) {
     var _a3, _b;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const res = await client.api.POST("/sandboxes/{sandboxID}/pause", {
       params: {
@@ -3325,9 +3363,9 @@ var SandboxApi = class {
    *
    * @returns snapshot information including the snapshot name that can be used with Sandbox.create().
    */
-  static async createSnapshot(sandboxId, opts) {
+  static async createSnapshot(target, opts) {
     var _a3;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const res = await client.api.POST("/sandboxes/{sandboxID}/snapshots", {
       params: {
@@ -3446,14 +3484,51 @@ var SandboxApi = class {
       }
       sandbox = res.data;
     }
+    return this.sandboxInfoFromCreate(sandbox, config, opts);
+  }
+  static async recoverSandboxCreate(recovery, opts) {
+    if (!recovery.idempotencyKey.trim()) {
+      throw new InvalidArgumentError(
+        "Sandbox create recovery requires an idempotency key"
+      );
+    }
+    const recoveryRegion = recovery.region ? ConnectionConfig.resolveRegion(recovery.region) : void 0;
+    if (recoveryRegion && (opts == null ? void 0 : opts.region) && ConnectionConfig.resolveRegion(opts.region) !== recoveryRegion) {
+      throw new InvalidArgumentError(
+        `Sandbox create recovery belongs to region "${recoveryRegion}", not "${opts.region}"`
+      );
+    }
+    const config = ConnectionConfig.forSandbox(__spreadProps(__spreadValues({}, opts), {
+      region: recoveryRegion != null ? recoveryRegion : opts == null ? void 0 : opts.region
+    }));
+    const signal = config.getSignal(opts == null ? void 0 : opts.requestTimeoutMs);
+    const sandbox = await this.waitForSandboxCreate(
+      new ApiClient(config),
+      __spreadProps(__spreadValues({}, recovery), {
+        region: config.region
+      }),
+      signal
+    );
+    return this.sandboxInfoFromCreate(sandbox, config, opts);
+  }
+  static async sandboxInfoFromCreate(sandbox, config, opts) {
     if ((0, import_compare_versions4.compareVersions)(sandbox.envdVersion, "0.1.0") < 0) {
-      await this.kill(sandbox.sandboxID, opts);
+      await this.kill(
+        {
+          sandboxId: sandbox.sandboxID,
+          region: sandbox.region
+        },
+        __spreadProps(__spreadValues({}, opts), {
+          region: sandbox.region
+        })
+      );
       throw new TemplateError(
         "You need to update the template to use the new SDK. You can do this by running `enclave template build` in the directory with the template."
       );
     }
     return {
       sandboxId: sandbox.sandboxID,
+      buildId: sandbox.buildID,
       sandboxDomain: sandbox.domain || void 0,
       sandboxRegion: sandbox.region,
       capacityTier: sandbox.capacityTier,
@@ -3467,7 +3542,13 @@ var SandboxApi = class {
     };
   }
   static async waitForSandboxCreate(client, recovery, signal) {
-    var _a3, _b;
+    var _a3, _b, _c;
+    let lastRecoveryError;
+    let recoveryRetryDelayMs = 25;
+    const waitToRetryRecovery = async () => {
+      await new Promise((resolve) => setTimeout(resolve, recoveryRetryDelayMs));
+      recoveryRetryDelayMs = Math.min(recoveryRetryDelayMs * 2, 1e3);
+    };
     while (!(signal == null ? void 0 : signal.aborted)) {
       let res;
       try {
@@ -3483,12 +3564,17 @@ var SandboxApi = class {
           }
         );
       } catch (cause) {
-        throw new OutcomeUnknownError(
-          "Sandbox admission committed, but its terminal result could not be recovered.",
-          recovery,
-          cause
-        );
+        lastRecoveryError = cause;
+        await waitToRetryRecovery();
+        continue;
+      }
+      const status = res.response.status;
+      if (status === 404 || status === 408 || status === 425 || status >= 500) {
+        lastRecoveryError = handleApiError(res);
+        await waitToRetryRecovery();
+        continue;
       }
+      recoveryRetryDelayMs = 25;
       const err = handleApiError(res);
       if (err) {
         throw err;
@@ -3507,13 +3593,13 @@ var SandboxApi = class {
     throw new OutcomeUnknownError(
       "Sandbox admission committed, but waiting for its terminal result timed out.",
       recovery,
-      signal == null ? void 0 : signal.reason
+      (_c = signal == null ? void 0 : signal.reason) != null ? _c : lastRecoveryError
     );
   }
-  static async connectSandbox(sandboxId, opts) {
+  static async connectSandbox(target, opts) {
     var _a3, _b;
     const timeoutMs = (_a3 = opts == null ? void 0 : opts.timeoutMs) != null ? _a3 : DEFAULT_SANDBOX_TIMEOUT_MS;
-    const config = ConnectionConfig.forSandbox(opts);
+    const { sandboxId, config } = resolveSandboxTarget(target, opts);
     const client = new ApiClient(config);
     const res = await client.api.POST("/sandboxes/{sandboxID}/connect", {
       params: {
@@ -3535,6 +3621,7 @@ var SandboxApi = class {
     }
     return {
       sandboxId: res.data.sandboxID,
+      buildId: res.data.buildID,
       sandboxDomain: res.data.domain || void 0,
       sandboxRegion: res.data.region,
       capacityTier: res.data.capacityTier,
@@ -3615,6 +3702,7 @@ var SandboxPaginator = class extends BasePaginator {
         var _a4;
         return __spreadProps(__spreadValues({
           sandboxId: sandbox.sandboxID,
+          buildId: sandbox.buildID,
           templateId: sandbox.templateID
         }, sandbox.alias && { name: sandbox.alias }), {
           metadata: (_a4 = sandbox.metadata) != null ? _a4 : {},
@@ -3681,8 +3769,14 @@ var Sandbox = class extends SandboxApi {
     this.mcpPort = 50005;
     this.connectionConfig = ConnectionConfig.forSandbox(opts);
     this.sandboxId = opts.sandboxId;
+    this.buildId = opts.buildId;
     this.sandboxDomain = (_a3 = opts.sandboxDomain) != null ? _a3 : this.connectionConfig.domain;
-    this.sandboxRegion = opts.sandboxRegion;
+    this.sandboxRegion = this.connectionConfig.debug ? opts.sandboxRegion : ConnectionConfig.resolveRegion(opts.sandboxRegion);
+    if (!this.connectionConfig.debug && this.connectionConfig.region !== this.sandboxRegion) {
+      throw new Error(
+        `Sandbox ${opts.sandboxId} belongs to region "${this.sandboxRegion}", not "${this.connectionConfig.region}"`
+      );
+    }
     this.capacityTier = opts.capacityTier;
     this.envdAccessToken = opts.envdAccessToken;
     this.trafficAccessToken = opts.trafficAccessToken;
@@ -3699,7 +3793,7 @@ var Sandbox = class extends SandboxApi {
       baseUrl: this.envdApiUrl,
       useBinaryFormat: false,
       interceptors: (opts == null ? void 0 : opts.logger) ? [createRpcLogger(opts.logger)] : void 0,
-      fetch: (url, options) => {
+      fetch: (url2, options) => {
         const headers = new Headers(this.connectionConfig.headers);
         new Headers(options == null ? void 0 : options.headers).forEach(
           (value, key) => headers.append(key, value)
@@ -3714,7 +3808,7 @@ var Sandbox = class extends SandboxApi {
           headers,
           redirect: "follow"
         });
-        return fetch(url, options);
+        return fetch(url2, options);
       }
     });
     this.envdApi = new EnvdApiClient(
@@ -3743,6 +3837,33 @@ var Sandbox = class extends SandboxApi {
     });
     this.git = new Git(this.commands);
   }
+  /**
+   * Serializable regional reference for reconnecting to this sandbox.
+   */
+  get ref() {
+    if (this.connectionConfig.debug) {
+      throw new Error("Sandbox references are unavailable in debug mode");
+    }
+    return {
+      sandboxId: this.sandboxId,
+      region: this.sandboxRegion
+    };
+  }
+  connectionOptions(opts) {
+    const ownerRegion = this.connectionConfig.debug ? this.connectionConfig.region : this.sandboxRegion;
+    if (!this.connectionConfig.debug && (opts == null ? void 0 : opts.region) && ConnectionConfig.resolveRegion(opts.region) !== ownerRegion) {
+      throw new Error(
+        `Sandbox ${this.sandboxId} belongs to region "${ownerRegion}", not "${opts.region}"`
+      );
+    }
+    return __spreadProps(__spreadValues(__spreadValues({}, this.connectionConfig), opts), {
+      apiUrl: this.connectionConfig.apiUrl,
+      sandboxUrl: this.connectionConfig.sandboxUrl,
+      domain: this.connectionConfig.domain,
+      debug: this.connectionConfig.debug,
+      region: ownerRegion
+    });
+  }
   /**
    * List all sandboxes.
    *
@@ -3753,6 +3874,20 @@ var Sandbox = class extends SandboxApi {
   static list(opts) {
     return new SandboxPaginator(opts);
   }
+  /**
+   * Create an immutable regional scope so repeated sandbox operations do not
+   * need to repeat the same region option.
+   *
+   * @example
+   * ```ts
+   * const yyz = Sandbox.inRegion("yyz")
+   * const sandbox = await yyz.create()
+   * const sameSandbox = await yyz.connect(sandbox.sandboxId)
+   * ```
+   */
+  static inRegion(region) {
+    return new SandboxRegionScope(this, region);
+  }
   static async create(templateOrOpts, opts) {
     var _a3, _b;
     const { template, sandboxOpts } = typeof templateOrOpts === "string" ? {
@@ -3766,6 +3901,7 @@ var Sandbox = class extends SandboxApi {
     if (config.debug) {
       return new this(__spreadValues({
         sandboxId: "debug_sandbox_id",
+        buildId: "debug_build_id",
         sandboxRegion: "debug",
         capacityTier: "shared",
         envdVersion: ENVD_DEBUG_FALLBACK
@@ -3776,7 +3912,9 @@ var Sandbox = class extends SandboxApi {
       (_a3 = sandboxOpts == null ? void 0 : sandboxOpts.timeoutMs) != null ? _a3 : this.defaultSandboxTimeoutMs,
       sandboxOpts
     );
-    const sandbox = new this(__spreadValues(__spreadValues({}, config), sandboxInfo));
+    const sandbox = new this(__spreadProps(__spreadValues(__spreadValues({}, config), sandboxInfo), {
+      region: sandboxInfo.sandboxRegion
+    }));
     if (sandboxOpts == null ? void 0 : sandboxOpts.mcp) {
       sandbox.mcpToken = crypto.randomUUID();
       const res = await sandbox.commands.run(
@@ -3794,6 +3932,51 @@ var Sandbox = class extends SandboxApi {
     }
     return sandbox;
   }
+  /**
+   * Recover a create whose authoritative response was lost without resending
+   * the original create payload.
+   *
+   * Pass `OutcomeUnknownError.recovery`. Recovery is pinned to the operation's
+   * owning region and cannot create a second sandbox with different options.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   return await Sandbox.create("base", { idempotencyKey: "job-123" })
+   * } catch (error) {
+   *   if (error instanceof OutcomeUnknownError) {
+   *     return Sandbox.recoverCreate(error.recovery)
+   *   }
+   *   throw error
+   * }
+   * ```
+   */
+  static async recoverCreate(recovery, opts) {
+    var _a3;
+    const config = ConnectionConfig.forSandbox(__spreadProps(__spreadValues({}, opts), {
+      region: (_a3 = recovery.region) != null ? _a3 : opts == null ? void 0 : opts.region
+    }));
+    const sandboxInfo = await SandboxApi.recoverSandboxCreate(recovery, opts);
+    const sandbox = new this(__spreadProps(__spreadValues(__spreadValues({}, config), sandboxInfo), {
+      region: sandboxInfo.sandboxRegion
+    }));
+    if (opts == null ? void 0 : opts.mcp) {
+      sandbox.mcpToken = crypto.randomUUID();
+      const res = await sandbox.commands.run(
+        `mcp-gateway --config '${JSON.stringify(opts.mcp)}'`,
+        {
+          user: "root",
+          envs: {
+            GATEWAY_ACCESS_TOKEN: sandbox.mcpToken
+          }
+        }
+      );
+      if (res.exitCode !== 0) {
+        throw new Error(`Failed to start MCP gateway: ${res.stderr}`);
+      }
+    }
+    return sandbox;
+  }
   static async betaCreate(templateOrOpts, opts) {
     var _a3, _b;
     const { template, sandboxOpts } = typeof templateOrOpts === "string" ? {
@@ -3807,6 +3990,7 @@ var Sandbox = class extends SandboxApi {
     if (config.debug) {
       return new this(__spreadValues({
         sandboxId: "debug_sandbox_id",
+        buildId: "debug_build_id",
         sandboxRegion: "debug",
         capacityTier: "shared",
         envdVersion: ENVD_DEBUG_FALLBACK
@@ -3817,7 +4001,9 @@ var Sandbox = class extends SandboxApi {
       (_a3 = sandboxOpts == null ? void 0 : sandboxOpts.timeoutMs) != null ? _a3 : this.defaultSandboxTimeoutMs,
       sandboxOpts
     );
-    const sandbox = new this(__spreadValues(__spreadValues({}, config), sandboxInfo));
+    const sandbox = new this(__spreadProps(__spreadValues(__spreadValues({}, config), sandboxInfo), {
+      region: sandboxInfo.sandboxRegion
+    }));
     if (sandboxOpts == null ? void 0 : sandboxOpts.mcp) {
       sandbox.mcpToken = crypto.randomUUID();
       const res = await sandbox.commands.run(
@@ -3839,9 +4025,11 @@ var Sandbox = class extends SandboxApi {
    * Connect to a sandbox. If the sandbox is paused, it will be automatically resumed.
    * Sandbox must be either running or be paused.
    *
-   * With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc).
+   * Persist {@link Sandbox.ref} to reconnect through the sandbox's owning
+   * regional API from another process or environment.
    *
-   * @param sandboxId sandbox ID.
+   * @param target sandbox ID, or a serializable reference containing its ID
+   * and owning region.
    * @param opts connection options.
    *
    * @returns A running sandbox instance
@@ -3855,13 +4043,15 @@ var Sandbox = class extends SandboxApi {
    * const sameSandbox = await Sandbox.connect(sandboxId)
    * ```
    */
-  static async connect(sandboxId, opts) {
-    const sandbox = await SandboxApi.connectSandbox(sandboxId, opts);
-    const config = ConnectionConfig.forSandbox(opts);
+  static async connect(target, opts) {
+    const sandbox = await SandboxApi.connectSandbox(target, opts);
+    const config = ConnectionConfig.forSandbox(__spreadValues(__spreadValues({}, opts), typeof target === "string" ? {} : { region: target.region }));
     return new this(__spreadProps(__spreadValues({}, config), {
-      sandboxId,
+      sandboxId: sandbox.sandboxId,
+      buildId: sandbox.buildId,
       sandboxDomain: sandbox.sandboxDomain,
       sandboxRegion: sandbox.sandboxRegion,
+      region: sandbox.sandboxRegion,
       capacityTier: sandbox.capacityTier,
       apiUrl: sandbox.apiUrl,
       envdAccessToken: sandbox.envdAccessToken,
@@ -3889,7 +4079,10 @@ var Sandbox = class extends SandboxApi {
    * ```
    */
   async connect(opts) {
-    await SandboxApi.connectSandbox(this.sandboxId, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    await SandboxApi.connectSandbox(
+      this.sandboxId,
+      this.connectionOptions(opts)
+    );
     return this;
   }
   /**
@@ -3958,7 +4151,11 @@ var Sandbox = class extends SandboxApi {
     if (this.connectionConfig.debug) {
       return;
     }
-    await SandboxApi.setTimeout(this.sandboxId, timeoutMs, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    await SandboxApi.setTimeout(
+      this.sandboxId,
+      timeoutMs,
+      this.connectionOptions(opts)
+    );
   }
   /**
    * Kill the sandbox.
@@ -3969,7 +4166,7 @@ var Sandbox = class extends SandboxApi {
     if (this.connectionConfig.debug) {
       return;
     }
-    await SandboxApi.kill(this.sandboxId, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    await SandboxApi.kill(this.sandboxId, this.connectionOptions(opts));
   }
   /**
    * Pause a sandbox by its ID.
@@ -3985,7 +4182,7 @@ var Sandbox = class extends SandboxApi {
    * ```
    */
   async pause(opts) {
-    return await SandboxApi.pause(this.sandboxId, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    return await SandboxApi.pause(this.sandboxId, this.connectionOptions(opts));
   }
   /**
    * Create a snapshot of the sandbox's current state.
@@ -4013,7 +4210,10 @@ var Sandbox = class extends SandboxApi {
    * ```
    */
   async createSnapshot(opts) {
-    return await SandboxApi.createSnapshot(this.sandboxId, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    return await SandboxApi.createSnapshot(
+      this.sandboxId,
+      this.connectionOptions(opts)
+    );
   }
   /**
    * List all snapshots created from this sandbox.
@@ -4023,7 +4223,7 @@ var Sandbox = class extends SandboxApi {
    * @returns paginator for listing snapshots from this sandbox.
    */
   listSnapshots(opts) {
-    return SandboxApi.listSnapshots(__spreadProps(__spreadValues(__spreadValues({}, this.connectionConfig), opts), {
+    return SandboxApi.listSnapshots(__spreadProps(__spreadValues({}, this.connectionOptions(opts)), {
       sandboxId: this.sandboxId
     }));
   }
@@ -4075,7 +4275,7 @@ var Sandbox = class extends SandboxApi {
     const filePath = path2 != null ? path2 : "";
     const fileUrl = this.fileUrl(filePath, username);
     if (useSignature) {
-      const url = new URL(fileUrl);
+      const url2 = new URL(fileUrl);
       const sig = await getSignature({
         path: filePath,
         operation: "write",
@@ -4083,11 +4283,11 @@ var Sandbox = class extends SandboxApi {
         expirationInSeconds: opts.useSignatureExpiration,
         envdAccessToken: this.envdAccessToken
       });
-      url.searchParams.set("signature", sig.signature);
+      url2.searchParams.set("signature", sig.signature);
       if (sig.expiration) {
-        url.searchParams.set("signature_expiration", sig.expiration.toString());
+        url2.searchParams.set("signature_expiration", sig.expiration.toString());
       }
-      return url.toString();
+      return url2.toString();
     }
     return fileUrl;
   }
@@ -4114,7 +4314,7 @@ var Sandbox = class extends SandboxApi {
     }
     const fileUrl = this.fileUrl(path2, username);
     if (useSignature) {
-      const url = new URL(fileUrl);
+      const url2 = new URL(fileUrl);
       const sig = await getSignature({
         path: path2,
         operation: "read",
@@ -4122,11 +4322,11 @@ var Sandbox = class extends SandboxApi {
         expirationInSeconds: opts.useSignatureExpiration,
         envdAccessToken: this.envdAccessToken
       });
-      url.searchParams.set("signature", sig.signature);
+      url2.searchParams.set("signature", sig.signature);
       if (sig.expiration) {
-        url.searchParams.set("signature_expiration", sig.expiration.toString());
+        url2.searchParams.set("signature_expiration", sig.expiration.toString());
       }
-      return url.toString();
+      return url2.toString();
     }
     return fileUrl;
   }
@@ -4138,7 +4338,10 @@ var Sandbox = class extends SandboxApi {
    * @returns information about the sandbox
    */
   async getInfo(opts) {
-    return await SandboxApi.getInfo(this.sandboxId, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    return await SandboxApi.getInfo(
+      this.sandboxId,
+      this.connectionOptions(opts)
+    );
   }
   /**
    * Get the metrics of the sandbox.
@@ -4162,7 +4365,10 @@ var Sandbox = class extends SandboxApi {
         );
       }
     }
-    return await SandboxApi.getMetrics(this.sandboxId, __spreadValues(__spreadValues({}, this.connectionConfig), opts));
+    return await SandboxApi.getMetrics(
+      this.sandboxId,
+      this.connectionOptions(opts)
+    );
   }
   fileUrl(path2, username) {
     const externalUrl = this.connectionConfig.getSandboxExternalUrl(
@@ -4173,19 +4379,105 @@ var Sandbox = class extends SandboxApi {
         port: this.envdPort
       }
     );
-    const url = new URL("/files", externalUrl);
+    const url2 = new URL("/files", externalUrl);
     if (username) {
-      url.searchParams.set("username", username);
+      url2.searchParams.set("username", username);
     }
     if (path2) {
-      url.searchParams.set("path", path2);
+      url2.searchParams.set("path", path2);
     }
-    return url.toString();
+    return url2.toString();
   }
 };
 Sandbox.defaultTemplate = "base";
 Sandbox.defaultMcpTemplate = "mcp-gateway";
 Sandbox.defaultSandboxTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
+var SandboxRegionScope = class {
+  constructor(sandboxClass, region) {
+    this.sandboxClass = sandboxClass;
+    this.selectedRegion = ConnectionConfig.resolveRegion(region);
+  }
+  get region() {
+    return this.selectedRegion;
+  }
+  options(opts) {
+    const requestedRegion = opts == null ? void 0 : opts.region;
+    if (requestedRegion && ConnectionConfig.resolveRegion(requestedRegion) !== this.region) {
+      throw new Error(
+        `Regional sandbox scope is pinned to "${this.region}", not "${requestedRegion}"`
+      );
+    }
+    return __spreadProps(__spreadValues({}, opts), {
+      region: this.region
+    });
+  }
+  list(opts) {
+    return this.sandboxClass.list(this.options(opts));
+  }
+  async create(templateOrOpts, opts) {
+    if (typeof templateOrOpts === "string") {
+      return this.sandboxClass.create(
+        templateOrOpts,
+        this.options(opts)
+      );
+    }
+    return this.sandboxClass.create(this.options(templateOrOpts));
+  }
+  recoverCreate(recovery, opts) {
+    if (recovery.region && ConnectionConfig.resolveRegion(recovery.region) !== this.region) {
+      throw new Error(
+        `Sandbox create recovery belongs to region "${recovery.region}", not "${this.region}"`
+      );
+    }
+    return this.sandboxClass.recoverCreate(
+      __spreadProps(__spreadValues({}, recovery), {
+        region: this.region
+      }),
+      this.options(opts)
+    );
+  }
+  async betaCreate(templateOrOpts, opts) {
+    if (typeof templateOrOpts === "string") {
+      return this.sandboxClass.betaCreate(
+        templateOrOpts,
+        this.options(opts)
+      );
+    }
+    return this.sandboxClass.betaCreate(
+      this.options(templateOrOpts)
+    );
+  }
+  connect(target, opts) {
+    return this.sandboxClass.connect(target, this.options(opts));
+  }
+  kill(target, opts) {
+    return this.sandboxClass.kill(target, this.options(opts));
+  }
+  getInfo(target, opts) {
+    return this.sandboxClass.getInfo(target, this.options(opts));
+  }
+  getFullInfo(target, opts) {
+    return this.sandboxClass.getFullInfo(target, this.options(opts));
+  }
+  getMetrics(target, opts) {
+    return this.sandboxClass.getMetrics(target, this.options(opts));
+  }
+  setTimeout(target, timeoutMs, opts) {
+    return this.sandboxClass.setTimeout(target, timeoutMs, this.options(opts));
+  }
+  pause(target, opts) {
+    return this.sandboxClass.pause(target, this.options(opts));
+  }
+  createSnapshot(target, opts) {
+    return this.sandboxClass.createSnapshot(target, this.options(opts));
+  }
+  listSnapshots(opts) {
+    return this.sandboxClass.listSnapshots(this.options(opts));
+  }
+  deleteSnapshot(snapshotId, opts) {
+    return this.sandboxClass.deleteSnapshot(snapshotId, this.options(opts));
+  }
+};
 
 // src/template/logger.ts
 var import_chalk = __toESM(require("chalk"));
@@ -4309,7 +4601,7 @@ function defaultBuildLogger(options) {
 var import_node_crypto = __toESM(require("crypto"));
 var import_node_fs = __toESM(require("fs"));
 var import_node_path = __toESM(require("path"));
-var import_node_url = require("url");
+var import_node_url = __toESM(require("url"));
 
 // src/template/consts.ts
 var FINALIZE_STEP_NAME = "finalize";
@@ -4457,7 +4749,7 @@ function getCallerDirectory(depth) {
     return void 0;
   }
   if (fileName.startsWith("file:")) {
-    fileName = (0, import_node_url.fileURLToPath)(fileName);
+    fileName = import_node_url.default.fileURLToPath(fileName);
   }
   return import_node_path.default.dirname(fileName);
 }
@@ -4548,7 +4840,7 @@ async function getFileUploadLink(client, { templateID, filesHash }, stackTrace)
   return fileUploadLinkRes.data;
 }
 async function uploadFile(options, stackTrace) {
-  const { fileName, url, fileContextPath, ignorePatterns, resolveSymlinks } = options;
+  const { fileName, url: url2, fileContextPath, ignorePatterns, resolveSymlinks } = options;
   try {
     const uploadStream = await tarFileStreamUpload(
       fileName,
@@ -4556,7 +4848,7 @@ async function uploadFile(options, stackTrace) {
       ignorePatterns,
       resolveSymlinks
     );
-    const res = await fetch(url, {
+    const res = await fetch(url2, {
       method: "PUT",
       // @ts-expect-error
       body: uploadStream,
@@ -4774,8 +5066,8 @@ function waitForPort(port) {
   const cmd = `ss -tuln | grep :${port}`;
   return new ReadyCmd(cmd);
 }
-function waitForURL(url, statusCode = 200) {
-  const cmd = `curl -s -o /dev/null -w "%{http_code}" ${url} | grep -q "${statusCode}"`;
+function waitForURL(url2, statusCode = 200) {
+  const cmd = `curl -s -o /dev/null -w "%{http_code}" ${url2} | grep -q "${statusCode}"`;
   return new ReadyCmd(cmd);
 }
 function waitForProcess(processName) {
@@ -4980,6 +5272,7 @@ function handleCmdEntrypointInstruction(instruction, templateBuilder) {
 // src/template/activationApi.ts
 async function activateTemplate(build, options = {}) {
   assertBuildIdentity(build);
+  assertExpectedVersion(options.expectedVersion);
   const region = resolveRegion(options.region);
   const config = ConnectionConfig.forGlobal(options);
   const client = new ApiClient(config);
@@ -4996,7 +5289,8 @@ async function activateTemplate(build, options = {}) {
         buildID: build.buildId,
         active: true,
         requiredReadyNodes: options.requiredReadyNodes,
-        allowRemoteFallback: options.allowRemoteFallback
+        allowRemoteFallback: options.allowRemoteFallback,
+        expectedVersion: options.expectedVersion
       },
       signal: config.getSignal(options.requestTimeoutMs)
     }
@@ -5005,6 +5299,7 @@ async function activateTemplate(build, options = {}) {
 }
 async function deactivateTemplate(build, options = {}) {
   assertBuildIdentity(build);
+  assertExpectedVersion(options.expectedVersion);
   const region = resolveRegion(options.region);
   const config = ConnectionConfig.forGlobal(options);
   const client = new ApiClient(config);
@@ -5019,7 +5314,8 @@ async function deactivateTemplate(build, options = {}) {
       },
       body: {
         buildID: build.buildId,
-        active: false
+        active: false,
+        expectedVersion: options.expectedVersion
       },
       signal: config.getSignal(options.requestTimeoutMs)
     }
@@ -5030,6 +5326,9 @@ async function getTemplateActivation(templateId, options = {}) {
   if (!templateId.trim()) {
     throw new InvalidArgumentError("templateId is required");
   }
+  if (options.buildId !== void 0 && !options.buildId.trim()) {
+    throw new InvalidArgumentError("buildId must not be empty");
+  }
   const region = resolveRegion(options.region);
   const config = ConnectionConfig.forSandbox(__spreadProps(__spreadValues({}, options), { region }));
   const client = new ApiClient(config);
@@ -5040,6 +5339,9 @@ async function getTemplateActivation(templateId, options = {}) {
         path: {
           templateID: templateId,
           region
+        },
+        query: {
+          buildID: options.buildId
         }
       },
       signal: config.getSignal(options.requestTimeoutMs)
@@ -5055,6 +5357,100 @@ function assertBuildIdentity(build) {
 function resolveRegion(region) {
   return ConnectionConfig.resolveRegion(region);
 }
+function assertExpectedVersion(expectedVersion) {
+  if (expectedVersion !== void 0 && (!Number.isSafeInteger(expectedVersion) || expectedVersion < 0)) {
+    throw new InvalidArgumentError(
+      "expectedVersion must be a non-negative safe integer"
+    );
+  }
+}
+
+// src/template/tagHeadApi.ts
+async function getTemplateTagHead(client, templateId, tag, signal) {
+  assertTemplateAndTag(templateId, tag);
+  const response = await client.api.GET("/templates/{templateID}/tags/{tag}", {
+    params: {
+      path: {
+        templateID: templateId,
+        tag
+      }
+    },
+    signal
+  });
+  const error = handleApiError(response, TemplateError);
+  if (error) {
+    throw error;
+  }
+  if (!response.data) {
+    throw new TemplateError("Enclave API returned no template tag head");
+  }
+  return mapTagHead(response.data);
+}
+async function promoteTemplateTag(client, candidate, tag, expected, signal) {
+  var _a3, _b, _c, _d, _e, _f;
+  assertBuildIdentity2(candidate);
+  assertTemplateAndTag(candidate.templateId, tag);
+  assertExpectation(expected);
+  const response = await client.api.PUT("/templates/{templateID}/tags/{tag}", {
+    params: {
+      path: {
+        templateID: candidate.templateId,
+        tag
+      }
+    },
+    body: {
+      buildID: candidate.buildId,
+      expectedBuildID: expected == null ? void 0 : expected.buildId,
+      expectedVersion: (_a3 = expected == null ? void 0 : expected.version) != null ? _a3 : 0
+    },
+    signal
+  });
+  if (response.response.status === 409 && (((_b = response.error) == null ? void 0 : _b.code) === "tag_changed" || ((_c = response.error) == null ? void 0 : _c.code) === "concurrent_mutation")) {
+    const message = (_e = (_d = response.error) == null ? void 0 : _d.message) != null ? _e : "The template tag changed after it was read";
+    throw new TemplateTagConflictError({
+      templateId: candidate.templateId,
+      tag,
+      candidateBuildId: candidate.buildId,
+      expectedBuildId: expected == null ? void 0 : expected.buildId,
+      expectedVersion: (_f = expected == null ? void 0 : expected.version) != null ? _f : 0,
+      reason: response.error.code,
+      message: `409: ${message}. Fetch its current head with Template.getTagHead() before retrying.`
+    });
+  }
+  const error = handleApiError(response, TemplateError);
+  if (error) {
+    throw error;
+  }
+  if (!response.data) {
+    throw new TemplateError("Enclave API returned no promoted template tag");
+  }
+  return mapTagHead(response.data);
+}
+function mapTagHead(head) {
+  return {
+    tag: head.tag,
+    buildId: head.buildID,
+    version: head.version,
+    createdAt: new Date(head.createdAt)
+  };
+}
+function assertTemplateAndTag(templateId, tag) {
+  if (!templateId.trim() || !tag.trim()) {
+    throw new InvalidArgumentError("templateId and tag are required");
+  }
+}
+function assertBuildIdentity2(candidate) {
+  if (!candidate.templateId.trim() || !candidate.buildId.trim()) {
+    throw new InvalidArgumentError("templateId and buildId are required");
+  }
+}
+function assertExpectation(expected) {
+  if (expected !== null && (!expected.buildId.trim() || !Number.isSafeInteger(expected.version) || expected.version < 1)) {
+    throw new InvalidArgumentError(
+      "expected tag head must include a buildId and a positive safe-integer version"
+    );
+  }
+}
 
 // src/template/index.ts
 var _a2;
@@ -5306,6 +5702,42 @@ var TemplateBase = class {
     const client = new ApiClient(config);
     return getTemplateTags(client, { templateID: templateId });
   }
+  /**
+   * Get the authoritative traffic-selection token for one template tag.
+   *
+   * Pass the returned head directly to {@link promoteTag}; its monotonic
+   * version prevents concurrent releasers from silently overwriting each
+   * other.
+   */
+  static async getTagHead(templateId, tag, options) {
+    const config = ConnectionConfig.forGlobal(options);
+    const client = new ApiClient(config);
+    return getTemplateTagHead(
+      client,
+      templateId,
+      tag,
+      config.getSignal(options == null ? void 0 : options.requestTimeoutMs)
+    );
+  }
+  /**
+   * Atomically move one template tag to an exact ready, durable build.
+   *
+   * Use a head returned by {@link getTagHead} as `expected`. Pass `null` only
+   * when creating a tag that must not already exist. A concurrent change throws
+   * `TemplateTagConflictError`; fetch the head again before deciding whether to
+   * retry.
+   */
+  static async promoteTag(candidate, tag, expected, options) {
+    const config = ConnectionConfig.forGlobal(options);
+    const client = new ApiClient(config);
+    return promoteTemplateTag(
+      client,
+      candidate,
+      tag,
+      expected,
+      config.getSignal(options == null ? void 0 : options.requestTimeoutMs)
+    );
+  }
   fromDebianImage(variant = "stable") {
     return this.fromImage(`debian:${variant}`);
   }
@@ -5603,8 +6035,8 @@ var TemplateBase = class {
       })
     );
   }
-  gitClone(url, path2, options) {
-    const args = ["git", "clone", url];
+  gitClone(url2, path2, options) {
+    const args = ["git", "clone", url2];
     if (options == null ? void 0 : options.branch) {
       args.push(`--branch ${options.branch}`);
       args.push("--single-branch");
@@ -5856,7 +6288,7 @@ var TemplateBase = class {
         if (index + 1 >= 0 && index + 1 < this.stackTraces.length) {
           stackTrace = this.stackTraces[index + 1];
         }
-        const { present, url } = await getFileUploadLink(
+        const { present, url: url2 } = await getFileUploadLink(
           client,
           {
             templateID,
@@ -5864,12 +6296,12 @@ var TemplateBase = class {
           },
           stackTrace
         );
-        if (forceUpload && url != null || present === false && url != null) {
+        if (forceUpload && url2 != null || present === false && url2 != null) {
           await uploadFile(
             {
               fileName: src,
               fileContextPath: this.fileContextPath.toString(),
-              url,
+              url: url2,
               ignorePatterns: [
                 ...this.fileIgnorePatterns,
                 ...readDockerignore(this.fileContextPath.toString())
@@ -5990,6 +6422,8 @@ Template.exists = TemplateBase.exists;
 Template.assignTags = TemplateBase.assignTags;
 Template.removeTags = TemplateBase.removeTags;
 Template.getTags = TemplateBase.getTags;
+Template.getTagHead = TemplateBase.getTagHead;
+Template.promoteTag = TemplateBase.promoteTag;
 Template.toJSON = TemplateBase.toJSON;
 Template.toDockerfile = TemplateBase.toDockerfile;
 
@@ -6024,9 +6458,11 @@ var src_default = Sandbox;
   Sandbox,
   SandboxCreateRejectedError,
   SandboxError,
+  SandboxRegionScope,
   Template,
   TemplateBase,
   TemplateError,
+  TemplateTagConflictError,
   TimeoutError,
   defaultBuildLogger,
   getSignature,