withruntime 0.9.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcc3df961b7af1a6f8c2941b1e829ce2e7b4f0e1dfcc8a57a5b32159c89996e7
-  data.tar.gz: e664bcedb285f6edda1adc3e5fd05fc5a4bd2b304e2e8d64d5dd46420128984f
+  metadata.gz: 92aca2f2d4a8d94b0871172606a8608e07d916e2e7236adab4b5752409fb466e
+  data.tar.gz: 87b4a3b19035d177f07c5a98b5adf256e7eab48769c1f803850d10b552800f64
 SHA512:
-  metadata.gz: 28da69ad5124df7ff53dc9b2ce0d17b7bd3e9ef934512884433bfe1aea3fa0983b259ec5dc2ea50f2f9c138e19e8d296221ef6b895115762c13e5a69ef082d63
-  data.tar.gz: 5d468e2f92368d91bea955b684fffc05f8be9404aa54c3dae3434baa1e3882de718416ce341ea26a30a49966cf416d5f986a188ade46888971315018afc2ebf0
+  metadata.gz: 28866196e471465715beba471c141ae01a1de33f5b4fc66266a53dc5fc27f170c1d0f67920bbeff930ee4bcaf00a574768e4800d71b292b8cbe88426cca049c8
+  data.tar.gz: e1339ba49b930b10c79f043d5187906dfff71c0a2832f7dc5569b2cd0b5a62b1544f6b312ca9944d9bc384d7718eab8cfb32f11a8642e3782d29d06e6c96aee5

data/lib/withruntime/agents.rb

@@ -59,8 +59,10 @@ module WithRuntime
   #   session.events.each { |event| puts event.text if event.kind == "reply" }
   #
   # A definition is a Hash, by snake_case keyword (+memory_mib:+) or by the
-  # API's own key ("memoryMiB"): +command+ (required), +from+ ({ image: } or
-  # { snapshot: }), +vcpu+ and +memory_mib+ (4 vCPU and 8 GiB unless set; a
+  # API's own key ("memoryMiB"): +command+ (required), +from+ ({ image: },
+  # { snapshot: }, or { repo: "owner/name" }: a repository connected to
+  # CI/CD, each session a copy of its warm snapshot, checked out at
+  # /workspace/repo), +vcpu+ and +memory_mib+ (4 vCPU and 8 GiB unless set; a
   # definition from a snapshot takes neither, InvalidRequestError, since a
   # snapshot keeps its own size), +instructions+, +env+, +secrets+ (names of
   # egress secrets: model keys go here), +mcp+ ([{ name:, url: }]), +volumes+
@@ -69,17 +71,18 @@ module WithRuntime
   # unless set: the session and every session under it, the root's covering
   # its tree; a tree at it stops, reason "budget"), +max_day_dollars+ (more
   # than 0, at most 100000, 100 unless set: the agent's sessions started that
-  # UTC day; an agent at it starts nothing new, ConflictError
-  # +budget_reached+, until the next day) and +template+ ("support" or
+  # UTC day; an agent at it starts nothing new, +budget_reached+
+  # (402), until the next day) and +template+ ("support" or
   # "team").
   class Agents < Product
-    attr_reader :sessions, :triggers, :templates
+    attr_reader :sessions, :triggers, :templates, :memory
 
     def initialize(transport)
       super
       @sessions = AgentSessions.new(transport)
       @triggers = AgentTriggers.new(transport)
       @templates = AgentTemplates.new
+      @memory = AgentMemory.new(transport)
       # Approvals come later, here: agents.approvals.list / answer.
     end
 
@@ -111,7 +114,7 @@ module WithRuntime
     # name for the conversation (a Slack thread, a pull request, one of your
     # customers such as "customer:42"), words with the same key join the open
     # session instead of starting a second; +session.joined+ says so. An agent
-    # at its day's budget is refused +budget_reached+ (ConflictError).
+    # at its day's budget is refused +budget_reached+ (402).
     def start(agent, input, key: nil, labels: nil, idempotency_key: nil)
       body = Fields.body(input: input, key: key, labels: labels)
       answer = @t.json("POST", "/v1/agents/#{seg(agent)}/sessions", body: body, key: idempotency_key)
@@ -310,6 +313,69 @@ module WithRuntime
     def delete(id) = @t.json("DELETE", "/v1/agents/triggers/#{seg(id)}") && nil
   end
 
+  # A page of an agent's memory files; +usage+ is the agent's whole memory,
+  # every scope: +bytes+, +files+, +limit_bytes+ and +limit_files+.
+  class AgentMemoryPage < Page
+    attr_reader :usage
+
+    def initialize(data, next_cursor, usage, &fetch)
+      super(data, next_cursor, &fetch)
+      @usage = usage
+    end
+  end
+
+  # +runtime.agents.memory+: an agent's built-in memory, text files its
+  # sessions keep across sessions and search. A +scope+ is whose: "" (the
+  # default) for what every session of the agent shares, or a session key such
+  # as "customer:42" for that key's alone. Up to 1 MiB a file, 1 GiB and
+  # 100,000 files an agent, billed as storage; past them a write is refused
+  # +memory_full+ (ConflictError).
+  #
+  #   runtime.agents.memory.write("helpdesk", "faq/refunds.md", "Refunds within 30 days.")
+  #   runtime.agents.memory.search("helpdesk", "refund").each { |hit| puts "#{hit.path}: #{hit.snippet}" }
+  class AgentMemory < Product
+    # The first page of an agent's files by scope and path, each with +scope+,
+    # +path+, +bytes+, +updated_at+ and +updated_by+; every scope unless
+    # +scope:+ is given. +each+ walks every page.
+    def list(agent, scope: nil, prefix: nil, cursor: nil, limit: nil)
+      memory_page(agent, { "scope" => scope, "prefix" => prefix, "limit" => limit }, cursor)
+    end
+
+    # The files whose words or path match +q+ (words, "a phrase", or, -not),
+    # best first, each with a +snippet+ and +rank+; every scope unless
+    # +scope:+ is given.
+    def search(agent, q, scope: nil, limit: nil)
+      body = @t.json("GET", "/v1/agents/#{seg(agent)}/memory", query: { "scope" => scope, "q" => q, "limit" => limit })
+      body["data"].map { |row| Record.new(row) }
+    end
+
+    # A file with its +content+; none there is NotFoundError.
+    def read(agent, path, scope: "")
+      Record.new(@t.json("GET", file(agent), query: { "scope" => scope, "path" => path }))
+    end
+
+    # Seeds or replaces a file; +created+ says which.
+    def write(agent, path, content, scope: "")
+      Record.new(@t.json("PUT", file(agent), query: { "scope" => scope, "path" => path }, body: { "content" => content }))
+    end
+
+    # Deletes a file; whether there was one.
+    def delete(agent, path, scope: "")
+      @t.json("DELETE", file(agent), query: { "scope" => scope, "path" => path })["deleted"] == true
+    end
+
+    private
+
+    def file(agent) = "/v1/agents/#{seg(agent)}/memory/content"
+
+    def memory_page(agent, query, cursor)
+      body = @t.json("GET", "/v1/agents/#{seg(agent)}/memory", query: query.merge("cursor" => cursor))
+      AgentMemoryPage.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"], Record.new(body["usage"] || {})) do |after|
+        memory_page(agent, query, after)
+      end
+    end
+  end
+
   # +runtime.agents.templates+: the five harnesses an agent can run, each
   # usable for either use, and the two uses.
   #

data/lib/withruntime/apps.rb

@@ -151,20 +151,28 @@ module WithRuntime
   #   deploy = runtime.apps.deploy(app.id, image: "web:latest", env: { "MODE" => "prod" }, wait: true)
   #   puts deploy.url
   #
-  # An App or Function: id, name, labels, state (waiting, live, failed,
+  # An App or Function: id, name, url (its address for life, its name then
+  # its account's: https://shop-3f9a1c2e7b04d915-acme1.runtimehost.com/; a rename leaves it,
+  # and its id's address answers too), labels, state (waiting, live, failed,
   # deleting, deleted), min_copies, max_copies, concurrency, spares, vcpu,
-  # memory_mib, port, health_path, live_version, previous_version, error
-  # ({code, message} or nil), created_at, updated_at, deleted_at, and
-  # release_watch (rollback, alert or off) where the API sends it.
+  # memory_mib, port, health_path, cdn, live_version, previous_version, error
+  # ({code, message} or nil), line (while a copy waits for room: lane,
+  # place, ahead by lane and words; nil otherwise), created_at, updated_at,
+  # deleted_at, and release_watch (alert, the default; rollback; or off). A Function
+  # also has sleep_after_ms (250 to 5000).
   #
   # A deploy: id, version, url and state (building, warming, switching, live,
   # failed, superseded); a failed or superseded one has error with code
-  # (deploy_build_failed, deploy_health_failed, deploy_superseded), message,
-  # hint and last_output. A version: version, live, previous, saved, deploy
-  # (its deploy's id) and build (nil for an image). A copy: id, version,
+  # (deploy_build_failed, deploy_health_failed, deploy_stop_failed,
+  # deploy_switch_failed, deploy_superseded), message, hint and last_output. A version: version,
+  # live, previous, saved, deploy (its deploy's id) and build (nil for an
+  # image). A copy: id, version,
   # region, state (starting, serving, draining, frozen, parked) and since.
   class Apps < ResourceProduct
     DEPLOY_ENDED = %w[live failed superseded].freeze
+    # Reconnections in a row with no new line before a log follow gives up.
+    LOG_RECONNECTS = 3
+    LOG_SEEN = 10_000
 
     # +path+: /v1/apps or /v1/functions.
     def initialize(transport, path = "/v1/apps")
@@ -173,9 +181,15 @@ module WithRuntime
 
     # Creates one waiting for its first version: +max_copies:+ (1 to 1000),
     # +vcpu:+ (1 to 16) and +memory_mib:+ (128 to 65536) are required;
-    # +concurrency:+, +spares:+, +port:+ (8080), +health_path:+, +name:+,
-    # +labels:+, and for an App +min_copies:+ (0). A Function leaves
-    # +min_copies+ out, zero included.
+    # +concurrency:+, +spares:+, +port:+ (8080), +health_path:+, +cdn:+ (true: Cloudflare's CDN in
+    # front of its addresses; false sends visitors straight to Runtime's routers,
+    # nothing cached), +name:+, +labels:+, +release_watch:+ ("alert" by default: tell the
+    # owners when a new version gets clearly worse in its first 15 minutes; "rollback" also
+    # goes back to the previous version; "off" does neither), and for an App
+    # +min_copies:+ (0). A Function leaves +min_copies+ out, zero included.
+    # A Function also takes +sleep_after_ms:+ (250 to 5000, default 1000): at
+    # most how long a copy stays awake after its last request ends; awake time
+    # with no request in flight is not billed. An App is refused it.
     def create(idempotency_key: nil, **fields) = super
 
     # Follows resource state, not a deploy: an older live version can survive
@@ -220,8 +234,115 @@ module WithRuntime
 
     def copies(id) = @t.json("GET", "#{@base}/#{seg(id)}/copies").map { |copy| Record.new(copy) }
 
+    # What its copies printed: lines (at, Unix milliseconds; stream, stdout
+    # or stderr; copy, a copy's id or nil; version or nil; text), oldest
+    # first, the newest +limit:+ (1 to 500; 100) in the window, with
+    # next_cursor and has_more. +since:+ is an RFC 3339 time or a duration
+    # back from now ("30s", "15m", "2h", "7d"; "1h" by default; 14 days at
+    # most). +version:+, +copy:+ and +stream:+ narrow it. Pass next_cursor as
+    # +cursor:+, with the same filters, for the page of older lines.
+    def logs(id, since: nil, version: nil, copy: nil, stream: nil, limit: nil, cursor: nil)
+      Record.new(@t.json("GET", "#{@base}/#{seg(id)}/logs", query: log_query(since, version, copy, stream, limit, cursor)))
+    end
+
+    # Each event to the block as its copies print (or an Enumerator without
+    # one), until the caller breaks out: a line (type "line", cursor, and a
+    # line's fields as for +logs+) or a gap where the store dropped lines
+    # (type "gap"); the stream goes on after it. A first follow sends the
+    # newest +limit:+ lines since +since:+, then new ones; +cursor:+ resumes
+    # after that line. Each follow the API ends after about two minutes is
+    # resumed from its cursor; a lost connection reconnects from the last
+    # line, up to three times in a row, then app_log_interrupted, whose details
+    # cursor resumes. An error event raises its own code and hint.
+    def follow_logs(id, since: nil, version: nil, copy: nil, stream: nil, limit: nil, cursor: nil, &block)
+      unless block
+        return enum_for(:follow_logs, id, since: since, version: version, copy: copy, stream: stream, limit: limit,
+                                          cursor: cursor)
+      end
+
+      follow_lines(id, log_query(since, version, copy, stream, limit, nil), cursor, &block)
+      nil
+    end
+
     private
 
+    def log_query(since, version, copy, stream, limit, cursor)
+      { "since" => since, "version" => version, "copy" => copy, "stream" => stream, "limit" => limit, "cursor" => cursor }
+    end
+
+    def log_invalid(cursor) = failure("app_log_invalid", "Retry the log from the last received cursor.", cursor)
+
+    def valid_log_line?(event)
+      event["text"].is_a?(String) && %w[stdout stderr].include?(event["stream"]) && valid_cursor?(event["cursor"]) &&
+        safe_integer?(event["at"]) && !event["at"].negative? && (event["copy"].nil? || event["copy"].is_a?(String)) &&
+        (event["version"].nil? || safe_integer?(event["version"]))
+    end
+
+    # Cursors are opaque positions: they cannot be ordered or counted on, so
+    # lines already given are known by their cursor.
+    def follow_lines(id, filters, cursor)
+      if cursor && !valid_cursor?(cursor)
+        raise failure("invalid_log_options", "Use the opaque cursor of a line or a continue event to resume.", cursor)
+      end
+
+      seen = cursor ? { cursor => true } : {}
+      failures = 0
+      loop do
+        continued = false
+        begin
+          # The API ends each follow after about two minutes, with a continue event.
+          @t.events("GET", "#{@base}/#{seg(id)}/logs", query: { "follow" => true }.merge(filters, { "cursor" => cursor }),
+                                                       timeout: 180) do |event|
+            raise log_invalid(cursor) unless event.is_a?(Hash)
+
+            case event["type"]
+            when "line"
+              raise log_invalid(cursor) unless valid_log_line?(event)
+              next if seen.key?(event["cursor"])
+
+              seen[event["cursor"]] = true
+              seen.delete(seen.first[0]) if seen.size > LOG_SEEN
+              cursor = event["cursor"]
+              failures = 0
+              yield Record.new(event)
+            when "gap"
+              raise log_invalid(cursor) unless valid_cursor?(event["cursor"])
+
+              cursor = event["cursor"]
+              yield Record.new(event)
+            when "continue"
+              raise log_invalid(cursor) unless event["cursor"].nil? || valid_cursor?(event["cursor"])
+
+              cursor = event["cursor"] || cursor
+              continued = true
+              break
+            when "error"
+              unless event["code"].is_a?(String) && !event["code"].empty? && event["hint"].is_a?(String) && !event["hint"].empty?
+                raise log_invalid(cursor)
+              end
+
+              raise failure(event["code"], event["hint"], cursor)
+            else
+              raise log_invalid(cursor)
+            end
+          end
+        rescue ConnectionError
+          nil # A lost connection, not a refusal: the transport retries retryable answers. Reconnect from the last line.
+        rescue Error => e
+          raise e unless e.code == "unexpected_answer" && e.status.zero?
+
+          raise failure("app_log_invalid", "The log contained invalid JSON; retry from details.cursor.", cursor)
+        end
+        failures += 1 unless continued
+        if failures > LOG_RECONNECTS
+          raise failure("app_log_interrupted", "Reconnect with follow_logs(id, cursor: details[\"cursor\"]).", cursor)
+        end
+
+        # A service that is down, or continuations one after another, never busy-loop.
+        sleep(0.05 * [1, failures].max)
+      end
+    end
+
     def read_deploy(id, deploy_id, wait_for, timeout_seconds, timeout)
       Record.new(@t.json("GET", "#{@base}/#{seg(id)}/deploys/#{seg(deploy_id)}",
                          query: { "waitFor" => wait_for, "timeoutSeconds" => timeout_seconds }, timeout: timeout))

data/lib/withruntime/builds.rb

@@ -18,7 +18,6 @@ module WithRuntime
     # Reconnections in a row with no new line before a follow gives up.
     RECONNECTS = 3
     SEEN = 10_000
-    SAFE_INTEGER = (2**53) - 1
 
     attr_reader :repositories
 
@@ -69,14 +68,8 @@ module WithRuntime
 
     def path(id) = "/v1/builds/#{seg(id)}"
 
-    def failure(code, hint, cursor) = Error.new(hint, code: code, hint: hint, details: { "cursor" => cursor })
-
     def invalid(cursor) = failure("build_log_invalid", "Retry the log from the last received cursor.", cursor)
 
-    def valid_cursor?(value)
-      value.is_a?(String) && !value.empty? && value.length <= 4096 && !value.match?(/[\x00-\x1f\x7f]/)
-    end
-
     def valid_failure?(value)
       return true if value.nil?
       return false unless value.is_a?(Hash)
@@ -86,8 +79,6 @@ module WithRuntime
         lines.is_a?(Array) && lines.size <= 20 && lines.all?(String)
     end
 
-    def safe_integer?(value) = value.is_a?(Integer) && value.abs <= SAFE_INTEGER
-
     def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
     # Cursors are opaque physical positions: they cannot be ordered or

data/lib/withruntime/ci.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # +runtime.ci+: CI/CD. A connected repository's checks run as jobs in
+  # sandboxes. In a private beta: an account outside it is refused with
+  # product_in_beta (403, PermissionDeniedError). Times are Unix milliseconds.
+  #
+  #   repo = runtime.ci.repositories.connect("acme/web")
+  #   check = runtime.ci.checks.list(repository_id: repo.id, state: ["failed"]).first
+  #   job = runtime.ci.checks.get(check.id).jobs.first
+  #   puts runtime.ci.jobs.get(job.id).log
+  class CI < Product
+    attr_reader :repositories, :checks, :jobs, :tests, :flakes
+
+    def initialize(transport)
+      super
+      @repositories = CIRepositories.new(transport)
+      @checks = CIChecks.new(transport)
+      @jobs = CIJobs.new(transport)
+      @tests = CITests.new(transport)
+      @flakes = CIFlakes.new(transport)
+    end
+  end
+
+  # +runtime.ci.repositories+: the repositories whose checks run.
+  #
+  # A repository: id, name, labels, repository (owner/name), production_branch,
+  # config_path, installation, github_repository_id, state (connected or
+  # disconnected), error, created_at, updated_at and deleted_at.
+  class CIRepositories < Product
+    # Connects +repository+ ("owner/name"), read through Runtime's GitHub App.
+    # Pushes and pull requests then run the checks written in +config_path:+
+    # (runtime.yml). Optional: production_branch (main), config_path,
+    # installation (the GitHub App installation to read it through; the newest
+    # when left out), name and labels.
+    def connect(repository, production_branch: nil, config_path: nil, installation: nil, name: nil, labels: nil,
+                idempotency_key: nil)
+      body = Fields.body(repository: repository, production_branch: production_branch, config_path: config_path,
+                         installation: installation, name: name, labels: labels)
+      Record.new(@t.json("POST", "/v1/ci/repositories", body: body, key: idempotency_key))
+    end
+
+    # +label+ is "key:value" strings, +state+ connected or disconnected.
+    def list(name: nil, label: nil, state: nil, limit: nil, cursor: nil)
+      page("/v1/ci/repositories", { "name" => name, "label" => label, "state" => state, "limit" => limit, "cursor" => cursor })
+    end
+
+    # Stops running its checks; the checks already run stay readable.
+    def disconnect(id, idempotency_key: nil)
+      Record.new(@t.json("DELETE", "/v1/ci/repositories/#{seg(id)}", key: idempotency_key))
+    end
+  end
+
+  # +runtime.ci.checks+: one run of a commit's jobs.
+  #
+  # A check: id, repository_id, repository, commit, branch, event, pull_request,
+  # base_commit, actor, trusted, waiting, approved_by, approved_at, landed,
+  # state (queued, running, passed, failed or cancelled), reason, counts (jobs
+  # per state), machines (where its machines came from and how soon, or nil),
+  # created_at, updated_at, started_at and ended_at.
+  class CIChecks < Product
+    # Checks, newest first. +state+ is any of queued, running, passed, failed,
+    # cancelled; +commit+ is a full sha.
+    def list(repository_id: nil, state: nil, branch: nil, commit: nil, pull_request: nil, limit: nil, cursor: nil)
+      page("/v1/ci/checks", { "repositoryId" => repository_id, "state" => state, "branch" => branch, "commit" => commit,
+                              "pullRequest" => pull_request, "limit" => limit, "cursor" => cursor })
+    end
+
+    # The check with its +jobs+ in plan order (no log).
+    def get(id) = Record.new(@t.json("GET", "/v1/ci/checks/#{seg(id)}"))
+  end
+
+  # +runtime.ci.jobs+: one command of a check, run in sandboxes.
+  class CIJobs < Product
+    # The job with its +log+ (the tail, at most 256 KiB). A failed job's
+    # sandbox_ids may be kept paused: wake one or exec in it with
+    # +runtime.sandboxes+. A review step's job has its +review+: the verdict
+    # (pass or block), summary, findings (kind, file, line, what, fix), notes,
+    # and the agent, account, model and session that gave it; nil otherwise.
+    def get(id) = Record.new(@t.json("GET", "/v1/ci/jobs/#{seg(id)}"))
+  end
+
+  # +runtime.ci.tests+: a repository's test files and their recent runs.
+  class CITests < Product
+    # Test files by name: file, ms, quarantined_since (their failures do not
+    # fail a check), runs and updated_at.
+    def list(repository_id, quarantined: nil, limit: nil, cursor: nil)
+      page("/v1/ci/tests", { "repositoryId" => repository_id, "quarantined" => quarantined, "limit" => limit, "cursor" => cursor })
+    end
+  end
+
+  # +runtime.ci.flakes+: tests that passed and failed on the same inputs, one
+  # run main's. Each is quarantined at once (it still runs and reports, and
+  # blocks nothing), or still gating when the repository protects it; handed
+  # to an owner with 48 hours to fix it or delete it with a reason; fixed once
+  # 100 runs of a main commit in parallel forks all pass.
+  #
+  # A flake: id, repository_id, file, state (quarantined, gating, fixed or
+  # deleted), gates, proof, again, owner (login, from, pull_request, branch),
+  # since, due_at, overdue, tried, prove_asked_at, delete_reason, ended_at,
+  # ended_check_id and updated_at; with a get or an update, its runs and
+  # failures too.
+  class CIFlakes < Product
+    # Flaky tests, newest first. +state+ is any of quarantined, gating (the
+    # open ones), fixed, deleted.
+    def list(repository_id: nil, state: nil, limit: nil, cursor: nil)
+      page("/v1/ci/flakes", { "repositoryId" => repository_id, "state" => state, "limit" => limit, "cursor" => cursor })
+    end
+
+    # The flake with its test file's newest 200 +runs+ (by commit and content
+    # key) and its +failures+' jobs, whose logs +runtime.ci.jobs.get+ reads.
+    def get(id) = Record.new(@t.json("GET", "/v1/ci/flakes/#{seg(id)}"))
+
+    # +prove: true+ asks for its 100 proof runs at main's next commit; +owner:+
+    # hands it to a GitHub login or org/team; +delete_reason:+ says why its
+    # test is deleted (it ends once main no longer holds the file).
+    def update(id, prove: nil, owner: nil, delete_reason: nil, idempotency_key: nil)
+      body = Fields.body(prove: prove, owner: owner, delete_reason: delete_reason)
+      Record.new(@t.json("POST", "/v1/ci/flakes/#{seg(id)}:update", body: body, key: idempotency_key))
+    end
+  end
+end

data/lib/withruntime/client.rb

@@ -23,9 +23,9 @@ module WithRuntime
   RENAME_RETIRES = nil
 
   class Client
-    attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :limits, :emails, :referrals,
+    attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :reservations, :limits, :emails, :referrals, :plans,
                 :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp, :agents,
-                :apps, :functions, :builds, :containers
+                :apps, :functions, :builds, :ci, :containers
 
     # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
     # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
@@ -56,9 +56,11 @@ module WithRuntime
       @images = Images.new(@transport)
       @volumes = Volumes.new(@transport)
       @secrets = Secrets.new(@transport)
+      @reservations = Reservations.new(@transport)
       @limits = Limits.new(@transport)
       @emails = Emails.new(@transport)
       @referrals = Referrals.new(@transport)
+      @plans = Plans.new(@transport)
       @switching = Switching.new(@transport)
       @events = Events.new(@transport)
       @webhooks = Webhooks.new(@transport)
@@ -77,6 +79,7 @@ module WithRuntime
       @apps = Apps.new(@transport, "/v1/apps")
       @functions = Apps.new(@transport, "/v1/functions")
       @builds = Builds.new(@transport)
+      @ci = CI.new(@transport)
       @containers = Containers.new(@transport)
     end
 

data/lib/withruntime/errors.rb

@@ -6,22 +6,33 @@ module WithRuntime
   # subclasses name the class of failure, as in the JavaScript, Python, Go and
   # Java SDKs.
   class Error < StandardError
-    # 503s that are a deliberate state, not a passing one: retrying cannot change them.
+    # Products switched off on this deployment (501; 503 from an older
+    # server): a deliberate state, not a passing one, so retrying cannot
+    # change them. Read only when the answer carries no +retryable+.
     DELIBERATE = %w[
-      unavailable unsupported fork_unavailable previews_unavailable
+      unavailable unsupported fork_unavailable previews_unavailable file_links_unavailable
       network_unavailable network_rules_unavailable secrets_unavailable identity_unavailable env_unavailable
-      resize_unavailable
+      resize_unavailable feature_unavailable delete_unavailable switch_image_unavailable switching_paused
+      schema_migration_required storage_unavailable
     ].freeze
     # Refusals that pass on their own: a host frees room, a sandbox of an
     # account without credit stops.
     PASSING = %w[no_capacity no_credit_running_limit no_credit_total_limit].freeze
     # Refusals of a create that clear when a sandbox stops or a host frees room.
     WAITS_FOR_ROOM = %w[no_credit_running_limit no_credit_total_limit no_credit_domain_limit no_credit_capacity_full quota_exceeded no_capacity volume_releasing].freeze
+    # Refusals that say nothing ran (a guest still busy, the API briefly
+    # busy, the caller's rate): sent again past max_retries, with growing
+    # waits, until the call's deadline.
+    NOTHING_RAN = %w[guest_busy busy rate_limited].freeze
 
-    attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after
+    attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after,
+                :retryable
 
-    def initialize(message, code:, status: 0, hint: nil, request_id: nil, details: nil, idempotency_key: nil, retry_after: nil)
+    def initialize(message, code:, status: 0, hint: nil, request_id: nil, details: nil, idempotency_key: nil,
+                   retry_after: nil, retryable: nil)
       super(message)
+      # The server's own word (true or false), or nil from an older server.
+      @retryable = [true, false].include?(retryable) ? retryable : nil
       @code = code
       @status = status
       @hint = hint
@@ -31,11 +42,23 @@ module WithRuntime
       @retry_after = retry_after
     end
 
-    # Whether retrying this exact call, with the same idempotency key, is safe and may work.
+    # The answer's own +retryable+, or nil when it sent none (an older server).
+    def sent_retryable
+      @retryable
+    end
+
+    # Whether retrying this exact call, with the same idempotency key, is safe
+    # and may work: the server's +retryable+ when it sent one, else worked out
+    # from the code and status as older servers need.
     def retryable?
+      return @retryable unless @retryable.nil?
       return false if DELIBERATE.include?(code)
       return details["field"] != "count" if PASSING.include?(code)
 
+      # The account at one of its limits (a 429): some free when its own work ends,
+      # some only when something is deleted, so the same call again is no answer by itself.
+      return false if code == "quota_exceeded"
+
       [0, 429, 502, 503, 504].include?(status)
     end
 
@@ -67,7 +90,8 @@ module WithRuntime
         request_id: error["requestId"],
         details: error["details"].is_a?(Hash) ? error["details"] : nil,
         idempotency_key: idempotency_key,
-        retry_after: retry_ms.is_a?(Numeric) ? retry_ms / 1000.0 : nil
+        retry_after: retry_ms.is_a?(Numeric) ? retry_ms / 1000.0 : nil,
+        retryable: error["retryable"]
       )
     end
 

data/lib/withruntime/products.rb

@@ -5,6 +5,8 @@ require "openssl"
 module WithRuntime
   # The pieces every product shares.
   class Product
+    SAFE_INTEGER = (2**53) - 1
+
     def initialize(transport)
       @t = transport
     end
@@ -13,6 +15,16 @@ module WithRuntime
 
     def seg(value) = Transport.segment(value)
 
+    # A followed log's refusal, with the cursor it resumes from in its details.
+    def failure(code, hint, cursor) = Error.new(hint, code: code, hint: hint, details: { "cursor" => cursor })
+
+    # A log cursor is opaque: a short string with no control characters.
+    def valid_cursor?(value)
+      value.is_a?(String) && !value.empty? && value.length <= 4096 && !value.match?(/[\x00-\x1f\x7f]/)
+    end
+
+    def safe_integer?(value) = value.is_a?(Integer) && value.abs <= SAFE_INTEGER
+
     # A change's body from keyword arguments: nil is left out, +:remove+ sends
     # null, which clears the field.
     def patch(changes)
@@ -96,13 +108,28 @@ module WithRuntime
   class Secrets < Product
     # Stores or replaces a secret for +hosts+ ("api.openai.com", "*.github.com").
     # With +header:+, that header is set on every request to them, +format:+'s
-    # {value} replaced. With +only:+ (<tt>{ labels: [{ role: "hub" }], sandboxes: [id] }</tt>),
-    # only those sandboxes get it instead of every sandbox of the organization: those whose
-    # labels hold every pair of any one selector, and those named by id. Left out when replacing
-    # a secret, the scope it has stays, so a new value never widens who gets it; +{}+ is every
-    # sandbox again.
-    def set(name, value:, hosts:, header: nil, format: nil, only: nil)
-      body = { "value" => value, "hosts" => hosts, "header" => header, "format" => format, "only" => only }.compact
+    # {value} replaced.
+    #
+    # +rules:+ limits the value to the requests a rule allows, such as
+    # [{ "methods" => ["GET"], "paths" => ["/repos/acme/*"] }]. +only:+ gives it to
+    # those sandboxes alone ({ "labels" => [{ "role" => "hub" }], "sandboxes" => [ids],
+    # "apps" => [App ids] }; left out when replacing, the scope it has stays; {} is every
+    # sandbox again). +github_app:+ ({ "id" =>, "installation" =>,
+    # "repositories" =>, "permissions" =>, "api" => }) makes +value+ a GitHub App's
+    # private key (PEM); the servers make its installation tokens themselves, and the
+    # secret takes no +header:+ or +format:+. +git:+ ({ "push" => [branch patterns] };
+    # an empty list is no push at all) limits what a git push may update. +api:+
+    # ({ "callsPerHour" =>, "writesPerHour" =>, "keep" =>, "copies" =>, "fresh" =>,
+    # "graphql" => { "path" =>, "mutations" => [] } }) sets each sandbox's hour with the
+    # secret, the far end's reserve, GraphQL's mutations and shared copies. The answer
+    # and +list+ return them as +githubApp+, +git+ and +api+. +env:+ is the environment
+    # variable sandboxes see it in, when not the secret's name. Secrets scoped to different
+    # sandboxes may share one, such as one GITHUB_TOKEN per repository; a write that would
+    # put two in one sandbox is refused (409). Absent when replacing: the variable it has stays.
+    def set(name, value:, hosts:, header: nil, format: nil, rules: nil, only: nil, github_app: nil, git: nil,
+            api: nil, env: nil)
+      body = { "value" => value, "hosts" => hosts, "header" => header, "format" => format, "rules" => rules,
+               "only" => only, "githubApp" => github_app, "git" => git, "api" => api, "env" => env }.compact
       Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}", body: body))
     end
 
@@ -155,6 +182,52 @@ module WithRuntime
     end
   end
 
+  # +runtime.plans+: monthly plans whose fee is prepaid usage. The fee comes back as plan usage, spent first
+  # each month at the same measured prices, plus a bonus for committing; plan usage left at the period's end
+  # ends with it. Money is integer microdollars in strings.
+  #
+  # Every change answers +checkout_url+ (where a person starts a first plan or a trial in the browser, nil
+  # once the change was made) and +current+ (the plan as it is now). Each takes an +idempotency_key+; one is
+  # made per call when left out.
+  class Plans < Product
+    # +current+ (the plan you hold, or nil: plan_id, name, status, interval, period_start, period_end,
+    # trial_ends_at, cancel_at_period_end, next_plan_id, started_at, add_ons, auto_upgrade, plan_usage) and
+    # +plans+ (every plan you may choose: id, name, card, fee_micros, yearly_fee_micros, bonus_micros,
+    # trial_days, first_period_double, support, collection, contract, position, included, limits, features,
+    # add_ons).
+    def list = Record.new(@t.json("GET", "/v1/plans"))
+
+    # Start a plan, or move to another. With no plan, answers +checkout_url+. A dearer plan starts at once,
+    # prorated; a cheaper one at +period_end+ (+next_plan_id+). +interval: "year"+ pays ten months for
+    # twelve; monthly unless asked.
+    def choose(plan, interval: nil, idempotency_key: nil)
+      body = { "plan" => plan }
+      body["interval"] = interval unless interval.nil?
+      Record.new(@t.json("POST", "/v1/plans/choose", body: body, key: idempotency_key))
+    end
+
+    # End the plan at +period_end+.
+    def cancel(idempotency_key: nil) = Record.new(@t.json("POST", "/v1/plans/cancel", body: {}, key: idempotency_key))
+
+    # Keep a plan you cancelled, before +period_end+.
+    def resume(idempotency_key: nil) = Record.new(@t.json("POST", "/v1/plans/resume", body: {}, key: idempotency_key))
+
+    # Add an add-on by id: charged now for the rest of the period, prorated, then with the plan.
+    def add_on(id, idempotency_key: nil)
+      Record.new(@t.json("POST", "/v1/plans/add-ons", body: { "addOn" => id }, key: idempotency_key))
+    end
+
+    # Remove an add-on: its charge stops now, and it holds to +period_end+.
+    def remove_add_on(id, idempotency_key: nil)
+      Record.new(@t.json("DELETE", "/v1/plans/add-ons/#{seg(id)}", key: idempotency_key))
+    end
+
+    # Move up a plan by itself when a limit refuses (true), or not. Owners, and keys an owner made.
+    def auto_upgrade(on, idempotency_key: nil)
+      Record.new(@t.json("PUT", "/v1/plans/auto-upgrade", body: { "on" => on }, key: idempotency_key))
+    end
+  end
+
   # +runtime.switching+: compare usage with a rival's published rates, and record a switch.
   class Switching < Product
     # Your settled usage over the last +days+ (30 by default, at most 90) priced

data/lib/withruntime/record.rb

@@ -47,6 +47,17 @@ module WithRuntime
     end
   end
 
+  # The files a traced command (+trace_files: true+) opened: +read+ is every
+  # file and directory it, and anything it started, opened (sorted absolute
+  # paths with links resolved, directories ending in "/"); +written+ every file
+  # it wrote. +truncated+ means some paths are missing, so do not treat the
+  # lists as complete.
+  class TracedFiles < Record
+    def read = self["read"] || []
+    def written = self["written"] || []
+    def truncated = self["truncated"] == true
+  end
+
   # A finished command. A timeout is a result (+timed_out+), not an exception.
   class CommandResult < Record
     def exit_code = self["exitCode"]
@@ -54,6 +65,9 @@ module WithRuntime
     def stderr = self["stderr"] || ""
     def timed_out = self["timedOut"] == true
     def ok? = !timed_out && exit_code == 0
+
+    # The files it read and wrote when it ran with +trace_files: true+; nil otherwise.
+    def files = self["files"] && TracedFiles.new(self["files"])
   end
 
   # One page of a list. +next_page+ reads the one after it; +each+ walks every

data/lib/withruntime/reservations.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "time"
+
+module WithRuntime
+  # +runtime.reservations+: book room for a burst. Holds room for +sandboxes+
+  # sandboxes of one size for a window (up to 24 hours, starting within 14 days)
+  # and answers at once, confirmed or declined. A decline is a normal answer
+  # (+status+ is "declined"; +reason+, +message+, +largest_sandboxes+ and
+  # +nearest_window+ say why and what would fit), not an error. In the window,
+  # creates are never refused no_capacity or quota_exceeded up to what you
+  # booked; running sandboxes are billed as usual and booked room none of your
+  # sandboxes use costs a quarter of the memory rate. +estimate_micros+ (the most
+  # it can cost: every sandbox running the whole window), +unused_rate_micros+
+  # (unused room per GiB-hour of memory, as quoted when booked),
+  # +unused_max_micros+ (the most it costs if none run) and
+  # +unused_charged_micros+ (charged so far) are microdollars as a string.
+  #
+  #   booking = runtime.reservations.create(sandboxes: 500, starts_at: Time.now + 3600, ends_at: Time.now + 3 * 3600)
+  #   booking.status # => "confirmed"
+  #
+  # Standing room (+keep+) is held from now until you cancel it, for a pool that
+  # deletes a sandbox after each use and makes another: a replacement is never
+  # refused up to it. With +snapshots+ it is held on the servers holding them,
+  # at their size; +for_key+ keeps it for this key's sandboxes alone. Its
+  # +ends_at+, +held_until+ and +unused_max_micros+ are nil;
+  # +unused_per_hour_micros+ is the most its unused room costs an hour.
+  #
+  #   pool = runtime.reservations.keep(sandboxes: 40, snapshots: [snapshot_id], for_key: true)
+  class Reservations < Product
+    # +starts_at+ and +ends_at+ are a Time or an ISO 8601 string. +vcpu+,
+    # +memory_mib+, +disk_mib+ and +region+ default to a create's defaults
+    # (2 vCPU, 4096 MiB each, the default region).
+    def create(sandboxes:, starts_at:, ends_at:, vcpu: nil, memory_mib: nil, disk_mib: nil, region: nil, idempotency_key: nil)
+      body = Fields.body(sandboxes: sandboxes, starts_at: iso(starts_at), ends_at: iso(ends_at),
+                         vcpu: vcpu, memory_mib: memory_mib, disk_mib: disk_mib, region: region)
+      Record.new(@t.json("POST", "/v1/reservations", body: body, key: idempotency_key))
+    end
+
+    # Keeps standing room for +sandboxes+ sandboxes until it is cancelled. Keep
+    # a few more than the pool runs, for deletes still finishing.
+    def keep(sandboxes:, snapshots: nil, for_key: nil, vcpu: nil, memory_mib: nil, disk_mib: nil, region: nil,
+             idempotency_key: nil)
+      body = Fields.body(standing: true, sandboxes: sandboxes, snapshots: snapshots, for_key: for_key || nil,
+                         vcpu: vcpu, memory_mib: memory_mib, disk_mib: disk_mib, region: region)
+      Record.new(@t.json("POST", "/v1/reservations", body: body, key: idempotency_key))
+    end
+
+    # Changes standing room in place: how many it holds, its snapshots, or
+    # both. It moves or grows only when all of it fits now; otherwise it raises
+    # no_capacity and nothing changes.
+    def update(id, sandboxes: nil, snapshots: nil, idempotency_key: nil)
+      body = Fields.body(sandboxes: sandboxes, snapshots: snapshots)
+      Record.new(@t.json("POST", "/v1/reservations/#{seg(id)}:update", body: body, key: idempotency_key))
+    end
+
+    # Bookings, newest first, as a Page (+data+, +next_cursor+, +more?+,
+    # +next_page+); iterating it walks every page.
+    def list(limit: nil, cursor: nil)
+      query = { "limit" => limit, "cursor" => cursor }
+      body = @t.json("GET", "/v1/reservations", query: query)
+      Page.new(body["items"].map { |item| Record.new(item) }, body["nextCursor"]) do |next_cursor|
+        list(limit: limit, cursor: next_cursor)
+      end
+    end
+
+    def get(id) = Record.new(@t.json("GET", "/v1/reservations/#{seg(id)}"))
+
+    # Gives the room back. The booking comes back with status "cancelled".
+    def cancel(id) = Record.new(@t.json("DELETE", "/v1/reservations/#{seg(id)}"))
+
+    private
+
+    def iso(at) = at.respond_to?(:iso8601) ? at.iso8601(3) : at
+  end
+end

data/lib/withruntime/sandbox.rb

@@ -165,7 +165,7 @@ module WithRuntime
     # limit so that +margin+ seconds remain, never more than the hour ahead the
     # API allows. A sandbox with no time limit needs none and is only watched.
     # Running time is billed as it is used. A paused sandbox is left paused; a
-    # stopped one ends the loop.
+    # stopped or deleted one ends the loop.
     def keep_alive(every: 60, margin: ApiDefaults::KEEP_ALIVE_MARGIN_SECONDS, &on_error)
       stop_keep_alive
       every = [10, every].max
@@ -182,6 +182,10 @@ module WithRuntime
               extend_lease([3600, need].min) if need >= 1
             end
           rescue Error => e
+            # Gone (deleted elsewhere, or by its own time limit): nothing to
+            # keep alive, and asking again would only be refused.
+            break if e.status == 404
+
             on_error&.call(e)
           end
           sleep(every)
@@ -222,7 +226,8 @@ module WithRuntime
              idempotency_key: nil)
       body = Fields.body(count: count, name: name, labels: labels, keep_snapshot: keep_snapshot,
                          secrets: secrets&.to_a)
-      reply = @t.json("POST", path(":fork"), body: body, wait: 60, key: idempotency_key)
+      # Its key replays a refusal for room or a limit, so it is told at once.
+      reply = @t.json("POST", path(":fork"), body: body, wait: 60, key: idempotency_key, room: 0)
       copies = reply["sandboxes"].map { |info| Sandbox.new(@t, info) }
       count.nil? ? copies.first : copies
     end
@@ -258,15 +263,17 @@ module WithRuntime
     # sandbox's; put secrets here), +stdin+, +timeout+ (seconds, default 60, up
     # to a day; a timeout is a result, not an error), +on_stdout+ and
     # +on_stderr+ (stream the command; the result keeps everything), and
-    # +check+ (raise CommandError on a non-zero exit or a timeout).
+    # +check+ (raise CommandError on a non-zero exit or a timeout), and
+    # +trace_files+ (the result's +files+ are the files it read and wrote; an
+    # older sandbox says to stop and start it, and no command runs).
     def exec(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
-             check: false, idempotency_key: nil)
+             check: false, idempotency_key: nil, trace_files: false)
       streamed = on_stdout || on_stderr || (timeout && timeout > 60)
       result = if streamed
                  collect(exec_stream(command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
-                                              idempotency_key: idempotency_key), on_stdout, on_stderr)
+                                              idempotency_key: idempotency_key, trace_files: trace_files), on_stdout, on_stderr)
                else
-                 body = command_body(command, cwd, env, stdin, timeout, user)
+                 body = command_body(command, cwd, env, stdin, timeout, user, trace_files)
                  CommandResult.new(@t.json("POST", path(":exec"), body: body, key: idempotency_key,
                                                                   timeout: timeout && (timeout + 60)))
                end
@@ -278,14 +285,14 @@ module WithRuntime
     # Runs a command and yields its events as they happen: start, stdout,
     # stderr, exit (each a Hash). Resumes by itself when the server ends a long
     # stream, so it never drops output. Without a block, an Enumerator.
-    def exec_stream(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, &block)
+    def exec_stream(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, trace_files: false, &block)
       unless block
         return enum_for(:exec_stream, command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
-                                               idempotency_key: idempotency_key)
+                                               idempotency_key: idempotency_key, trace_files: trace_files)
       end
 
       longest = ApiDefaults::STREAMED_EXEC_TIMEOUT_SECONDS
-      body = command_body(command, cwd, env, stdin, timeout || longest, user).merge("stream" => true)
+      body = command_body(command, cwd, env, stdin, timeout || longest, user, trace_files).merge("stream" => true)
       handed_over = nil
       process_id = nil
       cursor = 0
@@ -373,9 +380,11 @@ module WithRuntime
     # Starts a background process (a server, a watcher, a REPL) and returns at
     # once. It outlives your connection; +process(id)+ gets it back.
     # +pipe_stdin: true+ keeps input open for +write+; +pty: { cols:, rows: }+
-    # gives it a terminal.
-    def spawn(command, cwd: nil, user: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil, idempotency_key: nil)
-      body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout, user)
+    # gives it a terminal; +trace_files: true+ records the files it opens, read
+    # them with +files+ once it has ended.
+    def spawn(command, cwd: nil, user: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil,
+              idempotency_key: nil, trace_files: false)
+      body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout, user, trace_files)
       body["stdinMode"] = "pipe" if pipe_stdin
       body["pty"] = Fields.body(pty) if pty
       SandboxProcess.new(self, @t.json("POST", path("/processes"), body: body, key: idempotency_key))
@@ -391,20 +400,21 @@ module WithRuntime
 
     private
 
-    def lifecycle(verb, body, wait, key, room: 0)
+    def lifecycle(verb, body, wait, key, room: nil)
       @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, user)
+    def command_body(command, cwd, env, stdin, timeout, user, trace_files = false)
       body = command.is_a?(Array) ? { "argv" => command.map(&:to_s) } : { "command" => command.to_s }
       body["cwd"] = cwd if cwd
       body["user"] = user.to_s if user
       body["env"] = env.to_h { |key, value| [key.to_s, value.to_s] } if env
       body["stdinBase64"] = [stdin.to_s.b].pack("m0") unless stdin.nil?
       body["timeoutMs"] = (timeout * 1000).round if timeout
+      body["traceFiles"] = true if trace_files
       body
     end
 
@@ -423,7 +433,7 @@ module WithRuntime
           stderr << event["data"]
           on_stderr&.call(event["data"])
         when "truncated" then dropped = true
-        when "exit" then fields.merge!(event.slice("exitCode", "timedOut", "durationMs"))
+        when "exit" then fields.merge!(event.slice("exitCode", "timedOut", "durationMs", "files"))
         end
       end
       # A truncated event does not say which stream lost bytes, so both flags carry it.
@@ -495,6 +505,10 @@ module WithRuntime
     # Changes a PTY process's terminal size.
     def resize(cols, rows) = @sandbox.transport.json("POST", path(":resize"), body: { "cols" => cols, "rows" => rows })
 
+    # The files a process spawned with +trace_files: true+ read and wrote. Fails
+    # with process_running while it runs.
+    def files = TracedFiles.new(@sandbox.transport.json("GET", path("/files")))
+
     # Reads the process again.
     def refresh
       @info = Record.new(@sandbox.transport.json("GET", path))
@@ -630,6 +644,28 @@ module WithRuntime
       nil
     end
 
+    # A link anyone can open with no API key to download +path+ (a Hash with
+    # "url" and "expiresAt"). Range works. It lasts an hour by default, at most
+    # 7 days (+expires_in_seconds+). +filename+ saves it under that name;
+    # +wake+ true wakes a paused sandbox, false never does; +archive+ links a
+    # folder as a .tar.gz.
+    def download_url(path, expires_in_seconds: nil, filename: nil, wake: nil, archive: nil)
+      body = { "path" => path, "method" => "GET", "expiresInSeconds" => expires_in_seconds,
+               "filename" => filename, "wake" => wake, "archive" => archive }.compact
+      t.json("POST", @sandbox.path("/files:link"), body: body)
+    end
+
+    # A link anyone can PUT a raw body to with no API key: the body becomes the
+    # file at +path+, whole or not at all, up to +max_bytes+ (5 GiB at most).
+    def upload_url(path, expires_in_seconds: nil, max_bytes: nil, wake: nil)
+      body = { "path" => path, "method" => "PUT", "expiresInSeconds" => expires_in_seconds,
+               "maxBytes" => max_bytes, "wake" => wake }.compact
+      t.json("POST", @sandbox.path("/files:link"), body: body)
+    end
+
+    # Ends every link made for this sandbox so far.
+    def revoke_links = t.json("POST", @sandbox.path("/files:revoke-links"))
+
     # Copies a local file or directory in. A directory travels as one gzipped
     # tar to the API's folder routes, unpacked by the sandbox's own tar as it
     # arrives.

data/lib/withruntime/transport.rb

@@ -51,6 +51,10 @@ module WithRuntime
     # could refuse (the leader drill on vin-5, 4 October 2026). It is sent
     # again under the same key.
     ANSWER_START = 125.0
+    # The longest wait a server names that a call sleeps on (seconds). One
+    # longer (a daily cap's hour) is raised at once, still retryable with its
+    # retry_after, for the caller to schedule.
+    LONGEST_WAIT = 60.0
     class << self
       attr_writer :answer_start
 
@@ -375,14 +379,19 @@ module WithRuntime
     # Sends a call, retrying as the rules say, and returns the response once it
     # succeeded. With a block, the body is streamed to it.
     def send_call(http, method, path, query: nil, body: nil, raw: nil, accept: "application/json", wait: nil,
-                  key: nil, no_retry: false, room: 0, timeout: nil, cancel: nil, &stream)
+                  key: nil, no_retry: false, room: nil, timeout: nil, cancel: nil, &stream)
       write = method != "GET"
       key = write ? (key || SecureRandom.uuid) : nil
-      deadline = now + (timeout || @timeout) + room
-      room_until = now + room
+      # room: nil for a call with no room wait; 0 for a create, wake, restart
+      # or fork told at once.
+      deadline = now + (timeout || @timeout) + (room || 0)
+      room_until = now + (room || 0)
       room_attempt = 0
       payload = raw || (body.nil? ? nil : JSON.generate(body))
       attempt = 0
+      # An answer that ran nothing is sent again until the call's deadline
+      # (a Ruby call always has one: its timeout, plus any wait for room).
+      idle_attempt = 0
       # The last try never left, and was sent again at once.
       resent_at_once = false
       loop do
@@ -497,7 +506,9 @@ module WithRuntime
           { "error" => { "message" => text.strip.empty? ? nil : text.strip[0, 500] }.compact }
         end
         failure = Error.from(status, parsed, key)
-        if !no_retry && room.positive? && Error::WAITS_FOR_ROOM.include?(failure.code) && failure.details["field"] != "count"
+        # A quota on what is kept says it never clears by waiting.
+        if !no_retry && room&.positive? && Error::WAITS_FOR_ROOM.include?(failure.code) && failure.details["field"] != "count" &&
+           failure.sent_retryable != false
           room_left = room_until - now
           raise failure if room_left <= 0
 
@@ -506,15 +517,42 @@ module WithRuntime
           pause([room_left, wait_for].min, deadline, write, key, failure, cancel)
           next
         end
-        retryable = [429, 502, 503, 504].include?(status) && !Error::DELIBERATE.include?(failure.code)
-        raise failure if no_retry || !retryable || attempt >= max_retries
-
-        wait_for = failure.retry_after
-        if wait_for.nil?
-          header = Float(response["Retry-After"], exception: false)
-          wait_for = header&.positive? ? header : backoff(attempt)
+        header = Float(response["Retry-After"], exception: false)
+        header = nil unless header&.positive?
+        # The wait the server names, when it names one.
+        named = failure.retry_after || header
+        # Nothing ran: safe to send again for any call, past max_retries,
+        # with growing waits, until the deadline; then this refusal stands.
+        # A late answer's failure came after the work began, so only a
+        # guest's own refusal (guest_busy, before anything is journaled)
+        # still says nothing ran.
+        if [429, 503].include?(status) && Error::NOTHING_RAN.include?(failure.code) &&
+           failure.sent_retryable != false && (!late || failure.code == "guest_busy")
+          raise failure if named && named > LONGEST_WAIT
+
+          pause_for = [30.0, (named || 0.25) * (2**[idle_attempt, 3].min)].min * (0.9 + (rand * 0.2))
+          idle_attempt += 1
+          raise failure if pause_for >= deadline - now
+
+          pause(pause_for, deadline, write, key, failure, cancel)
+          next
         end
-        pause([30.0, wait_for].min * (0.9 + (rand * 0.2)), deadline, write, key, failure, cancel)
+        # The answer says whether the same call may work again; an older
+        # server that does not say is retried on 429, 502, 503 and 504. A
+        # refusal for room or the account's own limit is the room wait's on a
+        # create, wake, restart or fork; any other call retries what it says.
+        again = if failure.sent_retryable.nil?
+                  [429, 502, 503, 504].include?(status) && !Error::DELIBERATE.include?(failure.code)
+                else
+                  failure.sent_retryable
+                end
+        raise failure if no_retry || !again || (room && Error::WAITS_FOR_ROOM.include?(failure.code)) ||
+                         attempt >= max_retries
+        # A wait longer than a minute (a daily cap) is the caller's to
+        # schedule: the error says when, in retry_after.
+        raise failure if named && named > LONGEST_WAIT
+
+        pause([30.0, named || backoff(attempt)].min * (0.9 + (rand * 0.2)), deadline, write, key, failure, cancel)
         attempt += 1
       end
     end

data/lib/withruntime/version.rb

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

data/lib/withruntime.rb

@@ -11,6 +11,10 @@
 #   puts sbx.exec("python3 /workspace/invoice.py", check: true).stdout
 #   sbx.stop
 #
+# Agents are set up from a runtime.yml in your repo by the CLI, which makes
+# the account's agents match the file: npx withruntime agents deploy. This
+# gem has no deploy of its own.
+#
 # The guide is at https://withruntime.com/docs/ruby.
 require "json"
 require "openssl"
@@ -26,10 +30,12 @@ require_relative "withruntime/wallet"
 require_relative "withruntime/tar"
 require_relative "withruntime/sandbox"
 require_relative "withruntime/products"
+require_relative "withruntime/reservations"
 require_relative "withruntime/agents"
 require_relative "withruntime/images"
 require_relative "withruntime/apps"
 require_relative "withruntime/builds"
+require_relative "withruntime/ci"
 require_relative "withruntime/containers"
 require_relative "withruntime/network_products"
 require_relative "withruntime/parity_products"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: withruntime
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Runtime
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-22 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,
@@ -24,6 +24,7 @@ files:
 - lib/withruntime/api_defaults.rb
 - lib/withruntime/apps.rb
 - lib/withruntime/builds.rb
+- lib/withruntime/ci.rb
 - lib/withruntime/client.rb
 - lib/withruntime/containers.rb
 - lib/withruntime/credentials.rb
@@ -35,6 +36,7 @@ files:
 - lib/withruntime/parity_products.rb
 - lib/withruntime/products.rb
 - lib/withruntime/record.rb
+- lib/withruntime/reservations.rb
 - lib/withruntime/sandbox.rb
 - lib/withruntime/tar.rb
 - lib/withruntime/transport.rb