withruntime 0.5.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32515cd23a35b91a06324a7af01623f6dd75015c116e041c499e7a9b9548609c
-  data.tar.gz: 67454492f534d850643392417477f3f3d2782e7564bebb43555f76c6a1c9adfa
+  metadata.gz: b82967a1882d29df57dcef740f00077ce3a9afd05a1fdb6b031122438adfb92a
+  data.tar.gz: d79d6dc698f67d2e8fb8ee287f9830c243607cb7e127935ec6df6b21b2f2d736
 SHA512:
-  metadata.gz: 0ce1fea1e0289719efc5d1ece2a48181e8238a400c4abd25d3ed79c12661b6c28465acb33c43681f32dad71428c86a2bd94c11eae6692fbcc2d97e29d31c95c3
-  data.tar.gz: 07a2ef09506dd306e8843f1add75482ec75be67e696dcb3b9c66edec9d6b1540208914be83b2f165f89e92f9a54d3c4f27554d435b3ab74c8b5e7f2d67e0d866
+  metadata.gz: d3f846d1588e641fa9e781707be27af354a9b474e808b5657c918c6792a468b3cf49a08ea1eed6ecfe98591bec3d6935b3ff964c3382a8863ee143665ad936d0
+  data.tar.gz: 8839301368e7bf649663864afba4a313c7c0936b6c228888a6eb3d4ed72a517410502cf231f1f6e9da34d89c3ae8905fcb23307446700a68453a3d4e530bdae0

data/lib/withruntime/agents.rb

@@ -10,12 +10,44 @@ module WithRuntime
   end
 
   # One entry of a session's log: +seq+, +kind+ (input, answer, reply, ask,
-  # status, result, error or note), +actor+, +body+ and +created_at+. +text+
-  # is its words, +body.text+.
+  # status, result, error, note, or child: a child session's end, posted into
+  # its parent's log), +actor+, +body+ and +created_at+. +text+ is its words,
+  # +body.text+.
   class AgentEvent < Record
     def text = self["body"].is_a?(Hash) ? self["body"]["text"] : nil
   end
 
+  # A session as the API answers it. Times are ISO 8601 strings.
+  #
+  # +id+, +agent_id+, +agent_version+, +key+, +trigger+ (api, slack, github,
+  # schedule, webhook, or spawn: a child its parent's harness started),
+  # +state+ (queued, running, waiting, done, failed or stopped), +reason+
+  # (why it ended; among others "budget", "parent_ended", and "deleted" on a
+  # deleted record), +result+, +sandbox_id+, +last_seq+, +labels+,
+  # +created_at+, +started_at+, +ended_at+.
+  #
+  # Its tree: +parent_session_id+ (nil for a top session), +root_session_id+
+  # (itself for a top session) and +depth+ (0 to 3). Its use: +cost+ (this
+  # session's so far) and +tree_cost+ (it and every session under it), each
+  # an AgentCost. Its storage: +history_bytes+ (its log, kept until the
+  # session is deleted) and +attachment_bytes+ (its files and screenshots).
+  # +stop_why+ is why a stop was asked ("stopped", "budget" or
+  # "parent_ended") or nil, and +deleted_at+ is set once its history was
+  # deleted (+sessions.delete+).
+  class AgentSessionInfo < Record
+    def cost = AgentCost.new(self["cost"])
+    def tree_cost = AgentCost.new(self["treeCost"])
+    def deleted? = !self["deletedAt"].nil?
+  end
+
+  # What a session, or its tree, has used: +dollars+, +vcpu_seconds+ and
+  # +gib_seconds+ (0 when not given).
+  class AgentCost < Record
+    def dollars = self["dollars"] || 0
+    def vcpu_seconds = self["vcpuSeconds"] || 0
+    def gib_seconds = self["gibSeconds"] || 0
+  end
+
   # +runtime.agents+: agents that run in their own sandbox per session, started
   # by your own app through the API, Slack, GitHub, a schedule or a webhook. A private
   # beta: an account outside it is refused +product_in_beta+
@@ -28,14 +60,18 @@ module WithRuntime
   #
   # 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),
-  # +instructions+, +env+, +secrets+ (names of egress secrets: model keys go
-  # here), +mcp+ ([{ name:, url: }]), +volumes+ ([{ volume:, path: }]),
-  # +idle_pause_seconds+, +max_session_seconds+, +max_concurrent+,
-  # +max_session_dollars+ (5 unless set: a session at it stops, reason
-  # "budget"), +max_day_dollars+ (100 unless set: an agent at it starts nothing
-  # new, ConflictError +budget_reached+, until the next day) and +template+
-  # ("support" or "team").
+  # { snapshot: }), +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+
+  # ([{ volume:, path: }]), +idle_pause_seconds+, +max_session_seconds+,
+  # +max_concurrent+, +max_session_dollars+ (more than 0, at most 10000, 5
+  # 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
+  # "team").
   class Agents < Product
     attr_reader :sessions, :triggers, :templates
 
@@ -99,37 +135,42 @@ module WithRuntime
       AgentSession.new(@t, info, joined: false, seq: info["lastSeq"])
     end
 
-    # Deletes an ended session and its history; until then it is kept,
-    # counted as storage. An open session is refused +session_open+
-    # (ConflictError): stop it first.
+    # Deletes an ended session's history: its log, and every log under it in
+    # its tree. Until then the history is kept, counted as storage. The
+    # session is kept as a deleted record: +get+ still reads it, with
+    # +deleted_at+ set, +reason+ "deleted", +key+ and +result+ cleared and its
+    # cost kept (a delete never frees budget), and its log reads empty. An
+    # open session or tree is refused +session_open+ (ConflictError): stop it
+    # first.
     def delete(id) = @t.json("DELETE", "/v1/agents/sessions/#{seg(id)}") && nil
 
-    # The first page of sessions, as records; +each+ walks every page.
-    # +agent+ is an id or a name; +state+ is queued, running, waiting, done,
-    # failed or stopped; at most +limit+ a page.
-    def list(agent: nil, state: nil, cursor: nil, limit: nil)
-      sessions_page({ "agent" => agent, "state" => state, "limit" => limit }, cursor)
+    # The first page of sessions, as AgentSessionInfo records; +each+ walks
+    # every page. +agent+ is an id or a name; +state+ is queued, running,
+    # waiting, done, failed or stopped; +parent+ (a session's id) lists its
+    # direct children; +root+ (a top session's id) its whole tree, the root
+    # included; +deleted: true+ includes deleted records, hidden otherwise; at
+    # most +limit+ a page.
+    def list(agent: nil, state: nil, parent: nil, root: nil, deleted: nil, cursor: nil, limit: nil)
+      query = { "agent" => agent, "state" => state, "parent" => parent, "root" => root, "deleted" => deleted, "limit" => limit }
+      sessions_page(query, cursor)
     end
 
     private
 
     def sessions_page(query, cursor)
       body = @t.json("GET", "/v1/agents/sessions", query: query.merge("cursor" => cursor))
-      Page.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"]) { |after| sessions_page(query, after) }
+      Page.new(body["data"].map { |item| AgentSessionInfo.new(item) }, body["nextCursor"]) { |after| sessions_page(query, after) }
     end
   end
 
-  # A session of an agent. +info+ is its latest record: +state+ (queued,
-  # running, waiting, done, failed or stopped), +reason+, +result+,
-  # +last_seq+ and the rest; once the API sends them, +parent_session_id+ and
-  # +root_session_id+ (a child session's parent and its tree's root), +cost+
-  # ({ dollars, vcpuSeconds, gibSeconds } so far), +tree_cost+ (its children's
-  # summed in), +history_bytes+ (text history, counted as storage) and
-  # +attachment_bytes+ (files and screenshots, counted as storage), each nil
-  # until then; history is kept until the session is deleted
-  # (+sessions.delete+). +joined+ is whether +start+
-  # joined an open session with the same key, and +seq+ the number of the
-  # words it sent.
+  # A session of an agent. +info+ is its latest record, an AgentSessionInfo:
+  # +state+ (queued, running, waiting, done, failed or stopped), +reason+,
+  # +result+, +last_seq+, its tree (+parent_session_id+, +root_session_id+,
+  # +depth+), its use (+cost+, +tree_cost+), its storage (+history_bytes+,
+  # +attachment_bytes+), +stop_why+, +deleted_at+ and the rest; history is
+  # kept until the session is deleted (+sessions.delete+). +joined+ is
+  # whether +start+ joined an open session with the same key, and +seq+ the
+  # number of the words it sent.
   class AgentSession
     ENDED = %w[done failed stopped].freeze
     # How long the API holds an events read open, and the margin past it a
@@ -141,7 +182,7 @@ module WithRuntime
 
     def initialize(transport, info, joined: false, seq: nil)
       @t = transport
-      @info = Record.new(info)
+      @info = AgentSessionInfo.new(info)
       @joined = joined
       @seq = seq
     end
@@ -153,10 +194,15 @@ module WithRuntime
 
     # Reads the session again.
     def refresh(timeout: nil)
-      @info = Record.new(@t.json("GET", path, timeout: timeout))
+      @info = AgentSessionInfo.new(@t.json("GET", path, timeout: timeout))
       self
     end
 
+    # The first page of its direct children, the sessions its harness started
+    # (+trigger+ "spawn"), newest first; +each+ walks every page.
+    # +sessions.list(root:)+ reads a whole tree.
+    def children(cursor: nil, limit: nil) = AgentSessions.new(@t).list(parent: id, cursor: cursor, limit: limit)
+
     # Sends words into a running or waiting session and answers their seq.
     # The idempotency key, made here when not given, means a retried send is
     # never two messages. Named send_message, not send, so Ruby's own
@@ -192,7 +238,7 @@ module WithRuntime
     # Asks the session to stop and keeps the answer. A running session ends
     # once its sandbox is deleted; this does not wait for that (+wait+ does).
     def stop
-      @info = Record.new(@t.json("POST", path("/stop"), body: {}))
+      @info = AgentSessionInfo.new(@t.json("POST", path("/stop"), body: {}))
     end
 
     # The session once it has ended (done, failed or stopped); a failed

data/lib/withruntime/apps.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module WithRuntime
+  # A product built on the five verbs every resource shares (create, get,
+  # list, update, delete) and following one to a state: the same rules as the
+  # JavaScript SDK's resources.ts. One deadline covers a write, its retries
+  # and every read after it.
+  class ResourceProduct < Product
+    # A whole wait's deadline and its pause between reads.
+    class Following
+      attr_reader :key
+
+      def initialize(timeout, poll, key)
+        @poll = poll
+        @key = key
+        @deadline = timeout.positive? ? now + timeout : nil
+      end
+
+      # Seconds left for a call, or nil when the wait has no deadline (the
+      # client's own timeout then bounds each call).
+      def left = @deadline && [@deadline - now, 0.001].max
+
+      def expired? = !@deadline.nil? && now >= @deadline
+
+      def pause
+        sleep(@deadline ? [@poll, [@deadline - now, 0].max].min : @poll)
+        raise timed_out if expired?
+      end
+
+      def timed_out
+        ConnectionError.new("Waiting was cancelled or reached its deadline; the resource may still change.",
+                            code: "timeout", idempotency_key: key,
+                            hint: "Read the resource to resume waiting. Retry a write with the same idempotency_key.")
+      end
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # +path+ is the product's path (/v1/apps); a wait ends at its target or at
+    # any of +settled+, which raises the resource's own error.
+    def initialize(transport, path, settled)
+      super(transport)
+      @base = path
+      @settled = settled
+    end
+
+    # Creates one; defaults belong to the API, so the SDK sends none.
+    def create(idempotency_key: nil, **fields)
+      Record.new(@t.json("POST", @base, body: Fields.body(fields), key: idempotency_key))
+    end
+
+    # With +wait_for:+ the API holds the answer until that state or
+    # +timeout_seconds+ (1 to 60; 30 by default) pass. Check the state it returns.
+    def get(id, wait_for: nil, timeout_seconds: nil)
+      read(id, { "waitFor" => wait_for, "timeoutSeconds" => timeout_seconds },
+           wait_for && ((timeout_seconds || 30) + 60))
+    end
+
+    # +label:+ is key:value filters that all must match; +state:+ defaults to
+    # the product's live states; +limit:+ 1 to 100 (50).
+    def list(name: nil, label: nil, state: nil, limit: nil, cursor: nil)
+      page(@base, { "name" => name, "label" => label, "state" => state, "limit" => limit, "cursor" => cursor })
+    end
+
+    # Fields left out stay as they are; +name: :remove+ clears the name.
+    def update(id, idempotency_key: nil, **changes)
+      Record.new(@t.json("POST", "#{@base}/#{seg(id)}:update", body: patch(changes), key: idempotency_key))
+    end
+
+    # Follows the resource's state to +target+, reading it every +poll+
+    # seconds (0.25) for at most +timeout+ seconds in all (300; 0 waits as long
+    # as it takes). Raises the resource's error when it settles elsewhere, and
+    # ConnectionError with code timeout at the deadline.
+    def wait(id, target, timeout: 300, poll: 0.25)
+      following(timeout, poll, nil) { |wait| follow(id, target, wait) }
+    end
+
+    # Deletes it. With +wait: true+, follows it to deleted under one
+    # idempotency key made before the first try, so a timed-out delete can be
+    # retried after a restart with the key its error carries.
+    def delete(id, wait: false, timeout: 300, poll: 0.25, idempotency_key: nil)
+      return remove(id, idempotency_key, nil) unless wait
+
+      key = idempotency_key || SecureRandom.uuid
+      following(timeout, poll, key) { |follow| follow(id, "deleted", follow, remove(id, key, follow.left)) }
+    end
+
+    private
+
+    def read(id, query = nil, timeout = nil)
+      Record.new(@t.json("GET", "#{@base}/#{seg(id)}", query: query, timeout: timeout))
+    end
+
+    def remove(id, key, timeout) = Record.new(@t.json("DELETE", "#{@base}/#{seg(id)}", key: key, timeout: timeout))
+
+    def follow(id, target, wait, initial = nil)
+      record = initial || read(id, nil, wait.left)
+      loop do
+        return record if record.state == target
+        if @settled.include?(record.state)
+          error = record["error"].is_a?(Hash) ? record["error"] : {}
+          raise Error.new(error["message"] || "Expected #{target}, but #{id} reached #{record.state}.",
+                          code: error["code"] || "unexpected_state", idempotency_key: wait.key,
+                          hint: "Read the resource and inspect its error before starting another change.",
+                          details: { "id" => id, "state" => record.state, "target" => target, "resource" => record.to_h })
+        end
+        wait.pause
+        record = read(id, nil, wait.left)
+      end
+    end
+
+    # One deadline covers the write, retries and every read. A read's failure
+    # still belongs to the write that started the wait, so it carries its key.
+    def following(timeout, poll, key)
+      check(timeout, "timeout")
+      check(poll, "poll")
+      wait = Following.new(timeout, poll, key)
+      begin
+        result = yield wait
+        raise wait.timed_out if wait.expired?
+
+        result
+      rescue Error => e
+        raise wait.timed_out if wait.expired?
+        raise e if key.nil? || e.idempotency_key
+
+        raise e.class.new(e.message, code: e.code, status: e.status, hint: e.hint, request_id: e.request_id,
+                                     details: e.details, idempotency_key: key, retry_after: e.retry_after)
+      end
+    end
+
+    def check(value, field)
+      return if value.is_a?(Numeric) && value.finite? && !value.negative?
+
+      raise Error.new("#{field} must be a finite, nonnegative number.", code: "invalid_request",
+                                                                        hint: "Fix the option and call again; nothing was sent.",
+                                                                        details: { "field" => field })
+    end
+  end
+
+  # +runtime.apps+ and +runtime.functions+: your server, deployed from an
+  # image or a build, kept running in copies (an App keeps +min_copies+ awake;
+  # a Function sleeps to zero). In a private beta: an account outside it is
+  # refused with product_in_beta (403, PermissionDeniedError).
+  #
+  #   app = runtime.apps.create(name: "web", max_copies: 3, vcpu: 1, memory_mib: 1024)
+  #   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,
+  # 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.
+  #
+  # 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,
+  # region, state (starting, serving, draining, frozen, parked) and since.
+  class Apps < ResourceProduct
+    DEPLOY_ENDED = %w[live failed superseded].freeze
+
+    # +path+: /v1/apps or /v1/functions.
+    def initialize(transport, path = "/v1/apps")
+      super(transport, path, %w[failed deleted live])
+    end
+
+    # 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.
+    def create(idempotency_key: nil, **fields) = super
+
+    # Follows resource state, not a deploy: an older live version can survive
+    # a failed rollout of a newer one. +target+ is "live" or "deleted".
+    def wait(id, target, timeout: 300, poll: 0.25) = super
+
+    # Deploys a new version from +image:+ (an image of this account: id,
+    # name, name:tag or name@version, ready) or +build:+ (a build's id), with
+    # +env:+, +port:+ and +health_path:+. +keep_env: true+ carries the last
+    # deploy's environment, still sealed, with +env:+'s names set over it.
+    # With +wait: true+, follows the deploy, under one idempotency key, until
+    # it is live, failed or superseded, and returns it (check its state).
+    def deploy(id, image: nil, build: nil, env: nil, keep_env: nil, port: nil, health_path: nil, wait: false,
+               timeout: 300, poll: 0.25, idempotency_key: nil)
+      unless image.nil? ^ build.nil?
+        raise ArgumentError, "Deploy exactly one of image: or build:; nothing was sent."
+      end
+
+      body = Fields.body(image: image, build: build, env: env, keep_env: keep_env, port: port, health_path: health_path)
+      write_deploy(id, "deploys", body, wait, timeout, poll, idempotency_key)
+    end
+
+    # A deploy, by the App's id and its own. With +wait_for:+ the API holds
+    # the answer until that state or +timeout_seconds+ pass.
+    def get_deploy(id, deploy_id, wait_for: nil, timeout_seconds: nil)
+      read_deploy(id, deploy_id, wait_for, timeout_seconds, wait_for && ((timeout_seconds || 30) + 60))
+    end
+
+    # Resumes following a deploy by id after a restart, without making another version.
+    def wait_deploy(id, deploy_id, timeout: 300, poll: 0.25)
+      following(timeout, poll, nil) do |wait|
+        follow_deploy(id, read_deploy(id, deploy_id, nil, nil, wait.left), wait)
+      end
+    end
+
+    # Goes back to the previous version, as a new deploy; +wait: true+ as for +deploy+.
+    def rollback(id, wait: false, timeout: 300, poll: 0.25, idempotency_key: nil)
+      write_deploy(id, "rollback", {}, wait, timeout, poll, idempotency_key)
+    end
+
+    def versions(id) = @t.json("GET", "#{@base}/#{seg(id)}/versions").map { |version| Record.new(version) }
+
+    def copies(id) = @t.json("GET", "#{@base}/#{seg(id)}/copies").map { |copy| Record.new(copy) }
+
+    private
+
+    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))
+    end
+
+    def follow_deploy(id, record, wait)
+      until DEPLOY_ENDED.include?(record.state)
+        record = read_deploy(id, record.id, "live", 60, wait.left)
+        wait.pause unless DEPLOY_ENDED.include?(record.state)
+      end
+      record
+    end
+
+    def write_deploy(id, verb, body, wait, timeout, poll, idempotency_key)
+      write = ->(key, left) { Record.new(@t.json("POST", "#{@base}/#{seg(id)}/#{verb}", body: body, key: key, timeout: left)) }
+      return write.call(idempotency_key, nil) unless wait
+
+      key = idempotency_key || SecureRandom.uuid
+      following(timeout, poll, key) { |follow| follow_deploy(id, write.call(key, follow.left), follow) }
+    end
+  end
+end

data/lib/withruntime/builds.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # +runtime.builds+: a connected repository's commit built into the server an
+  # App or Function deploys. In a private beta: an account outside it is
+  # refused with product_in_beta (403, PermissionDeniedError).
+  #
+  #   repo = runtime.builds.repositories.connect(provider: "github", repository: "acme/web", deploy: "app:#{app.id}")
+  #   build = runtime.builds.create(repository_id: repo.id, ref: "main")
+  #   runtime.builds.logs(build.id, follow: true) { |event| puts event.text if event.type == "line" }
+  #
+  # A build: id, name, labels, repository_id, ref, branch, commit, state
+  # (queued, fetching, building, deploying, succeeded, failed, cancelled,
+  # superseded), reason, timings (milliseconds per step once done, or nil),
+  # output_snapshot_id, error, created_at, updated_at and deleted_at.
+  class Builds < Product
+    TERMINAL = %w[succeeded failed cancelled superseded].freeze
+    # 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
+
+    def initialize(transport)
+      super
+      @repositories = Repositories.new(transport)
+    end
+
+    # Builds +ref+ of a connected repository. The same +branch:+ and commit is
+    # one build; a newer build of the branch supersedes older ones not ended.
+    def create(repository_id:, ref:, branch: nil, name: nil, labels: nil, idempotency_key: nil)
+      body = Fields.body(repository_id: repository_id, ref: ref, branch: branch, name: name, labels: labels)
+      Record.new(@t.json("POST", "/v1/builds", body: body, key: idempotency_key))
+    end
+
+    def get(id) = Record.new(@t.json("GET", path(id)))
+
+    def list(name: nil, label: nil, state: nil, limit: nil, cursor: nil)
+      page("/v1/builds", { "name" => name, "label" => label, "state" => state, "limit" => limit, "cursor" => cursor })
+    end
+
+    # Cancels a build; one that already ended stays as it is.
+    def cancel(id, idempotency_key: nil) = Record.new(@t.json("POST", "#{path(id)}:cancel", key: idempotency_key))
+
+    # The last 200 lines and the failing step: lines (cursor, at, step, text,
+    # stream), cursor, state, reason, failing_step (name, exit_code,
+    # last_lines), has_more and next_cursor; +page_cursor:+ pages older lines.
+    #
+    # With +follow: true+, each event to the block as it is written (or an
+    # Enumerator without one), until the build ends: a line (type "line"), a
+    # gap where lines were lost (type "gap", earliest_cursor), then one
+    # terminal event (state, reason, failing_step). +cursor:+ resumes after
+    # that line. A lost connection reconnects from the last line, up to three
+    # times in a row; then build_log_interrupted, whose details cursor resumes.
+    # +timeout:+ bounds the whole follow, reconnections included (120 seconds;
+    # 0 for none).
+    def logs(id, follow: false, cursor: nil, page_cursor: nil, timeout: 120, &block)
+      unless follow
+        return Record.new(@t.json("GET", "#{path(id)}/logs", query: { "cursor" => cursor, "pageCursor" => page_cursor }))
+      end
+      return enum_for(:logs, id, follow: true, cursor: cursor, page_cursor: page_cursor, timeout: timeout) unless block
+
+      follow_logs(id, cursor, page_cursor, timeout, &block)
+      nil
+    end
+
+    private
+
+    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)
+
+      lines = value["lastLines"]
+      value["name"].is_a?(String) && (value["exitCode"].nil? || safe_integer?(value["exitCode"])) &&
+        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
+    # counted on, so lines already given are known by their cursor.
+    def follow_logs(id, cursor, page_cursor, timeout)
+      if (cursor && !valid_cursor?(cursor)) || page_cursor
+        raise failure("invalid_log_options", "Use an opaque cursor for follow; page_cursor is only for search pages.", cursor)
+      end
+
+      seen = cursor ? { cursor => true } : {}
+      failures = 0
+      deadline = timeout.positive? ? now + timeout : nil
+      timed_out = lambda do
+        ConnectionError.new("The log follow reached its deadline.", code: "timeout", details: { "cursor" => cursor },
+                                                                     hint: "Resume with logs(id, follow: true, cursor: details[\"cursor\"]).")
+      end
+      loop do
+        raise timed_out.call if deadline && now >= deadline
+
+        continued = false
+        begin
+          @t.events("GET", "#{path(id)}/logs", query: { "follow" => true, "cursor" => cursor },
+                                               timeout: deadline && (deadline - now)) do |event|
+            raise invalid(cursor) unless event.is_a?(Hash)
+            raise invalid(cursor) unless event.key?("cursor") && (event["cursor"].nil? || valid_cursor?(event["cursor"]))
+
+            case event["type"]
+            when "line"
+              unless event["text"].is_a?(String) && %w[stdout stderr].include?(event["stream"]) &&
+                     safe_integer?(event["at"]) && !event["at"].negative? &&
+                     (event["step"].nil? || event["step"].is_a?(String)) && valid_cursor?(event["cursor"])
+                raise invalid(cursor)
+              end
+              next if seen.key?(event["cursor"])
+
+              seen[event["cursor"]] = true
+              seen.delete(seen.first[0]) if seen.size > SEEN
+              cursor = event["cursor"]
+              failures = 0
+              yield Record.new(event)
+            when "gap"
+              raise invalid(cursor) if !valid_cursor?(event["earliestCursor"]) || (cursor && event["cursor"] != cursor)
+
+              cursor = event["cursor"]
+              yield Record.new(event)
+            when "terminal"
+              if (cursor && event["cursor"] != cursor) || !TERMINAL.include?(event["state"]) ||
+                 !event["reason"].is_a?(String) || event["reason"].empty? || !valid_failure?(event["failingStep"]) ||
+                 (event["state"] != "failed" && !event["failingStep"].nil?)
+                raise invalid(cursor)
+              end
+
+              yield Record.new(event)
+              return
+            when "continue"
+              if cursor && event["cursor"] != cursor
+                raise failure("build_log_gap", "Resume from details.cursor; report a persistent missing log line.", cursor)
+              end
+
+              cursor = event["cursor"]
+              continued = true
+              break
+            when "error"
+              unless event["cursor"] == cursor && event["code"].is_a?(String) && !event["code"].empty? &&
+                     event["hint"].is_a?(String) && !event["hint"].empty?
+                raise invalid(cursor)
+              end
+
+              raise failure(event["code"], event["hint"], cursor)
+            else
+              raise invalid(cursor)
+            end
+          end
+        rescue ConnectionError
+          # A lost connection, not a refusal: the transport itself retries
+          # retryable answers. Reconnect from the last line.
+          raise timed_out.call if deadline && now >= deadline
+        rescue Error => e
+          raise e unless e.code == "unexpected_answer" && e.status.zero?
+
+          raise failure("build_log_invalid", "The log contained invalid JSON; retry from details.cursor.", cursor)
+        end
+        failures += 1 unless continued
+        if failures > RECONNECTS
+          raise failure("build_log_interrupted", "Reconnect with logs(id, follow: true, cursor: details[\"cursor\"]).", cursor)
+        end
+
+        # A service that is down, or continuations one after another, never busy-loop.
+        pause = 0.05 * [1, failures].max
+        pause = [pause, [deadline - now, 0].max].min if deadline
+        sleep(pause)
+      end
+    end
+  end
+
+  # +runtime.builds.repositories+: the repositories Runtime builds. Every push
+  # to a repository's production branch builds it and deploys it to its
+  # +deploy+ target. In the Builds private beta (product_in_beta, 403, outside it).
+  #
+  # A repository: id, name, labels, provider (github or git), repository,
+  # deploy (app:<id>, function:<id> or container:<id>), production_branch,
+  # previews, root_directory, install_command, build_command, start_command,
+  # port, health_path, build_env, state (connected or disconnected), error,
+  # created_at, updated_at and deleted_at.
+  class Repositories < Product
+    # Connects +repository+ from +provider+ ("github" or "git") to +deploy+.
+    # Optional: production_branch, previews, root_directory, install_command
+    # (chosen by the lockfile when left out), build_command, start_command
+    # (the build then ends as that server, answering health_path with 200),
+    # port, health_path, build_env (never a secret: anyone who reads the
+    # repository sees it), name and labels.
+    def connect(provider:, repository:, deploy:, idempotency_key: nil, **settings)
+      body = Fields.body(settings.merge(provider: provider, repository: repository, deploy: deploy))
+      Record.new(@t.json("POST", "/v1/repositories", body: body, key: idempotency_key))
+    end
+
+    def list(name: nil, label: nil, state: nil, limit: nil, cursor: nil)
+      page("/v1/repositories", { "name" => name, "label" => label, "state" => state, "limit" => limit, "cursor" => cursor })
+    end
+
+    # Changes settings in place; its id and builds stay. Fields left out stay
+    # as they are; +:remove+ clears name, install_command, build_command,
+    # start_command or health_path.
+    def update(id, idempotency_key: nil, **changes)
+      Record.new(@t.json("POST", "/v1/repositories/#{seg(id)}:update", body: patch(changes), key: idempotency_key))
+    end
+
+    def disconnect(id, idempotency_key: nil) = Record.new(@t.json("DELETE", "/v1/repositories/#{seg(id)}", key: idempotency_key))
+
+    # A link (url, expires_at) to install Runtime's GitHub App, so private
+    # repositories build. Open it in a browser within 15 minutes, install the
+    # App where Runtime may read, then connect the repository with provider github.
+    def install_github = Record.new(@t.json("POST", "/v1/repositories/github:install"))
+  end
+end

data/lib/withruntime/client.rb

@@ -24,7 +24,8 @@ module WithRuntime
 
   class Client
     attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :limits, :emails, :referrals,
-                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp, :agents
+                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp, :agents,
+                :apps, :functions, :builds, :containers
 
     # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
     # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
@@ -72,6 +73,11 @@ module WithRuntime
       @sso = SSO.new(@transport)
       @mcp = MCP.new(@transport)
       @agents = Agents.new(@transport)
+      # Private beta: outside it, product_in_beta (403).
+      @apps = Apps.new(@transport, "/v1/apps")
+      @functions = Apps.new(@transport, "/v1/functions")
+      @builds = Builds.new(@transport)
+      @containers = Containers.new(@transport)
     end
 
     # Renamed on 6 October 2026, one plural word per product: each old name is the product it became, with a warning,

data/lib/withruntime/containers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # +runtime.containers+: one OCI image's process on its own microVM, billed
+  # at the sandbox rates, at /v1/containers. In a private beta: an account
+  # outside it is refused with product_in_beta (403, PermissionDeniedError).
+  #
+  #   box = runtime.containers.create(image: "nginx:1.27", vcpu: 1, memory_mib: 512, name: "web")
+  #   box = runtime.containers.wait(box.id, "running")
+  #   puts box.port
+  #
+  # A container: id, name, labels, state (waiting, running, sleeping, stopped,
+  # failed, deleting, deleted), image (pinned to its digest), entrypoint,
+  # command, working_dir, user, port (or nil), exposed_ports, on_exit, sleep,
+  # vcpu, memory_mib, env_names (the environment's names, never its values),
+  # error ({code, message} or nil), created_at, updated_at and deleted_at.
+  class Containers < ResourceProduct
+    def initialize(transport)
+      super(transport, "/v1/containers", %w[failed deleted])
+    end
+
+    # Runs one copy of +image:+ (an OCI reference; the answer pins its digest)
+    # with +vcpu:+ (1 to 16) and +memory_mib:+ (128 to 65536), all required.
+    # +entrypoint:+ replaces the image's Entrypoint and drops its Cmd;
+    # +command:+ replaces its Cmd. +env:+ is set over the image's own and never
+    # read back, only its names. +port:+ (1 to 65535) is required when the
+    # image exposes several TCP ports. +on_exit:+ is "restart" or "stop": by
+    # default it restarts when it serves a port, else stops. It never sleeps
+    # unless +sleep: true+. Also +name:+, +labels:+, +working_dir:+ and +user:+.
+    def create(idempotency_key: nil, **fields) = super
+
+    # Only +name:+ and +labels:+ change; +name: :remove+ clears the name.
+    def update(id, idempotency_key: nil, **changes) = super
+
+    # Follows its state to +target+ ("running", say); reaching failed or
+    # deleted first raises with its error.
+    def wait(id, target, timeout: 300, poll: 0.25) = super
+  end
+end

data/lib/withruntime/fields.rb

@@ -3,9 +3,9 @@
 module WithRuntime
   # Ruby's snake_case keywords as the API's camelCase fields: +timeout_seconds:+
   # is timeoutSeconds, +memory_mib:+ is memoryMiB. User data (labels, env,
-  # build_args, headers and the like) is sent as it is.
+  # build_args, build_env, headers and the like) is sent as it is.
   module Fields
-    OPAQUE = %w[labels env buildArgs headers data context detail].freeze
+    OPAQUE = %w[labels env buildArgs buildEnv headers data context detail].freeze
 
     module_function
 

data/lib/withruntime/products.rb

@@ -13,6 +13,14 @@ module WithRuntime
 
     def seg(value) = Transport.segment(value)
 
+    # A change's body from keyword arguments: nil is left out, +:remove+ sends
+    # null, which clears the field.
+    def patch(changes)
+      body = Fields.body(changes.reject { |_key, value| value == :remove })
+      changes.each { |key, value| body[key.is_a?(Symbol) ? Fields.camel(key) : key.to_s] = nil if value == :remove }
+      body
+    end
+
     def page(path, query)
       body = @t.json("GET", path, query: query)
       Page.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"]) do |cursor|

data/lib/withruntime/sandbox.rb

@@ -25,6 +25,12 @@ module WithRuntime
     # 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.
+    #
+    # +secrets: [name, ...]+ is the egress secrets this sandbox may use, by
+    # name: only those of your egress secrets that would otherwise reach it.
+    # +[]+ is none; leave it out for every secret that reaches it. Fixed for
+    # the sandbox's life; a copy of a snapshot may only narrow its source's
+    # list. +sbx.info.secrets+ reads it back, nil for every secret.
     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,
@@ -208,8 +214,14 @@ module WithRuntime
     # run. One copy without +count+; an array with it. If a copy fails, the
     # error's +details["startedSandboxIds"]+ names the copies that did start.
     # +funding+ is accepted and ignored: copies run on free usage first, then credit.
-    def fork(count: nil, name: nil, labels: nil, keep_snapshot: nil, funding: nil, idempotency_key: nil)
-      body = Fields.body(count: count, name: name, labels: labels, keep_snapshot: keep_snapshot)
+    # +secrets: [name, ...]+ is the egress secrets the copies may use, by name:
+    # only those of your egress secrets that would otherwise reach them. +[]+
+    # is none; leave it out to keep this sandbox's list. Fixed for the copies'
+    # life; it may only narrow this sandbox's list.
+    def fork(count: nil, name: nil, labels: nil, keep_snapshot: nil, funding: nil, secrets: nil,
+             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)
       copies = reply["sandboxes"].map { |info| Sandbox.new(@t, info) }
       count.nil? ? copies.first : copies

data/lib/withruntime/version.rb

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

data/lib/withruntime.rb

@@ -28,6 +28,9 @@ require_relative "withruntime/sandbox"
 require_relative "withruntime/products"
 require_relative "withruntime/agents"
 require_relative "withruntime/images"
+require_relative "withruntime/apps"
+require_relative "withruntime/builds"
+require_relative "withruntime/containers"
 require_relative "withruntime/network_products"
 require_relative "withruntime/parity_products"
 require_relative "withruntime/file_watch"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: withruntime
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Runtime
@@ -22,7 +22,10 @@ files:
 - lib/withruntime.rb
 - lib/withruntime/agents.rb
 - lib/withruntime/api_defaults.rb
+- lib/withruntime/apps.rb
+- lib/withruntime/builds.rb
 - lib/withruntime/client.rb
+- lib/withruntime/containers.rb
 - lib/withruntime/credentials.rb
 - lib/withruntime/errors.rb
 - lib/withruntime/fields.rb