withruntime 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e403c64b0fd311fd7ba3fb2a9fab6304afda36100ebc1fe0bd30f6b8f82bcece
-  data.tar.gz: a6eb390df90ab8f676704e8181c535d2dd23a41eebec44efdbf0219f46f675c6
+  metadata.gz: 53b4e63218b0587cacbd8e0ad8ec583ba4ce9b32ec0b792208b8f70750b5acd5
+  data.tar.gz: 3461a8000fc4817de3f06c6f6f40b6e5d29b49312a4e1f9c9dc94a649e91b8ae
 SHA512:
-  metadata.gz: a9994df04fad6ef2af83e9c1bb92e037b42e048bdf2806465d5969e43f7bc4ba9862fcbc77036d61b7d826579f9e0c316e302b05822cf6c326e6739a657ef677
-  data.tar.gz: de3343c87c44ea8dbed899137c0034de4683f64cb2ff44029ffcfbd6da98652f68d4fae8b53fbc90d3dc00a4ba5305d0239190eb756d8dff95ee54f0c0584043
+  metadata.gz: b1bb2aea12c2959b3afcd694ad90124d1c04fcf60201fdece3f5f1264b40bfa3b3f8deec865c5265d806b6e8c389ebacfd4da833648133fdba93b9ece3d7352f
+  data.tar.gz: d0238775905bea2408a2d930a402f49a4001bf900c3a8c13acbd511aaf5c486b7b01da8b5f93dfc188e50b696e135b8b92dfd75a7f9c74f5d4dcbdfcce63b668

data/lib/withruntime/client.rb

@@ -33,7 +33,7 @@ module WithRuntime
     # +timeout+: seconds for each call, retries included (300).
     # +max_retries+: of transport failures, 429, 502, 503 and 504 (4).
     # +max_connections+: calls in flight at once; streams do not count (32).
-    # +wait_for_capacity+: seconds a sandbox create keeps retrying, with the
+    # +wait_for_capacity+: seconds a sandbox create, wake or restart keeps retrying, with the
     # same key and input, when the slots without credit, quota or region are full (120; 0 fails at once).
     def initialize(api_key: nil, base_url: nil, timeout: 300, max_retries: 4, max_connections: 32,
                    wait_for_capacity: 120, env: ENV, in_sandbox: -> { Credentials.in_runtime_sandbox? })

data/lib/withruntime/products.rb

@@ -104,7 +104,7 @@ module WithRuntime
     end
   end
 
-  # +runtime.limits+: whether this key is read-only, and what its agent may still spend today.
+  # +runtime.limits+: whether this key is read-only, and what its agent may still spend today, plus +account+: the account's limits (limit, label, unit, max, used), or nil.
   class Limits < Product
     def get = Record.new(@t.json("GET", "/v1/limits"))
   end

data/lib/withruntime/sandbox.rb

@@ -19,6 +19,12 @@ module WithRuntime
     # free, up to +wait_for_capacity+ seconds (the client's, two minutes by default).
     #
     #   runtime.sandboxes.create(labels: { team: "search" }, timeout_seconds: 900)
+    #
+    # +spread_from: [id, ...]+ (one to 16 ids of your own sandboxes or snapshots)
+    # starts it on a server none of them is on. With no other server that has
+    # room, the create raises +no_capacity+ and nothing is made or charged.
+    # +sbx.info.placement+ is an opaque tag for its server: the same tag means
+    # the same server.
     def create(wait: true, idempotency_key: nil, wait_for_capacity: nil, **fields)
       room = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
       info = @t.json("POST", "/v1/sandboxes", body: Fields.body(fields), wait: wait ? 60 : 0,
@@ -118,8 +124,12 @@ module WithRuntime
 
     # Carries on a paused sandbox, with its memory and processes;
     # +timeout_seconds+ is its new time limit, for a sandbox that has one.
-    def wake(wait: true, timeout_seconds: nil, idempotency_key: nil)
-      lifecycle("wake", timeout_seconds ? { "timeoutSeconds" => timeout_seconds } : {}, wait, idempotency_key)
+    # When its server has no room (+no_capacity+) it waits for room, as +create+
+    # does, up to +wait_for_capacity+ seconds (the client's, two minutes by
+    # default; 0 fails at once), sending the same idempotency key each time.
+    def wake(wait: true, timeout_seconds: nil, idempotency_key: nil, wait_for_capacity: nil)
+      lifecycle("wake", timeout_seconds ? { "timeoutSeconds" => timeout_seconds } : {}, wait, idempotency_key,
+                room: room_for(wait_for_capacity))
     end
 
     # Moves a sandbox's time limit on, at most an hour ahead of now. A sandbox
@@ -130,7 +140,10 @@ module WithRuntime
     def set_retention(days, idempotency_key: nil) = lifecycle("retention", { "days" => days }, false, idempotency_key)
 
     # Starts a stopped persistent sandbox again from its disk. Memory is not kept.
-    def restart(wait: true, idempotency_key: nil) = lifecycle("restart", {}, wait, idempotency_key)
+    # Waits for room like +wake+ when its server is full.
+    def restart(wait: true, idempotency_key: nil, wait_for_capacity: nil)
+      lifecycle("restart", {}, wait, idempotency_key, room: room_for(wait_for_capacity))
+    end
 
     # Changes name, labels, auto_wake, idle_pause_seconds, persistent or
     # max_total_cost_micros; fields left out stay as they are, and
@@ -203,8 +216,10 @@ module WithRuntime
     end
 
     # Keeps this sandbox's whole machine as a snapshot to start new sandboxes
-    # from. A running sandbox is paused for the moment it takes, then woken; a
-    # paused one stays paused. A sandbox with volumes cannot be snapshotted.
+    # from. A running sandbox is paused by the server for the moment it takes
+    # and woken once the capture is over (one still capturing when the call
+    # answers stays paused until it is ready); a paused one stays paused. A
+    # sandbox with volumes cannot be snapshotted.
     def snapshot(name: nil, labels: nil, retention_days: nil, idempotency_key: nil)
       refresh
       # Straight after a fork or a wake the sandbox is still resuming, and
@@ -213,15 +228,11 @@ module WithRuntime
       if %w[resuming starting].include?(state) then wait_for("running")
       elsif state == "pausing" then wait_for("paused")
       end
-      running = state == "running"
-      pause if running
-      begin
-        Record.new(@t.json("POST", path(":snapshot"),
-                           body: Fields.body(name: name, labels: labels, retention_days: retention_days),
-                           wait: 10, key: idempotency_key))
-      ensure
-        wake if running
-      end
+      # The server pauses a running sandbox itself: a client pause and wake
+      # would be two more round trips.
+      Record.new(@t.json("POST", path(":snapshot"),
+                         body: Fields.body(name: name, labels: labels, retention_days: retention_days),
+                         wait: 10, key: idempotency_key))
     end
 
     # CPU and memory over a range: 15m, 1h, 6h, 24h, 7d or 30d.
@@ -367,11 +378,13 @@ module WithRuntime
 
     private
 
-    def lifecycle(verb, body, wait, key)
-      @info = Record.new(@t.json("POST", path(":#{verb}"), body: body, wait: wait ? 60 : 0, key: key))
+    def lifecycle(verb, body, wait, key, room: 0)
+      @info = Record.new(@t.json("POST", path(":#{verb}"), body: body, wait: wait ? 60 : 0, key: key, room: room))
       self
     end
 
+    def room_for(wait_for_capacity) = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
+
     def command_body(command, cwd, env, stdin, timeout)
       body = command.is_a?(Array) ? { "argv" => command.map(&:to_s) } : { "command" => command.to_s }
       body["cwd"] = cwd if cwd

data/lib/withruntime/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WithRuntime
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: withruntime
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Runtime
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies: []
 description: 'Linux sandboxes for agents, and every other Runtime Cloud product: streaming
   commands and terminals, files and watches, images, durable volumes and backups,