withruntime 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f471d00ffe082a8a507a514dda86ce4062342e2b5f0e27153309d094a27fb35b
-  data.tar.gz: 988ff09e0b418238acb50eba94f81bfa59c579e8103a81bd8b43e551c692f70e
+  metadata.gz: c855551b3670978d87aab0540d48736b4f9f0935cb8109cbb9a6bdbf85b05d96
+  data.tar.gz: c2e545740a78cc37fdcdec6de993c4b12402906f68a0bd3692d07f357bd17c4e
 SHA512:
-  metadata.gz: e4e8625a16d34f127de6bda5733b2645b733cb7a06ec3af65d87fc48a6b804d17c6d22f03cc657bd3cb64d8c29e3269cc42047aed28b0cf084f25a6cba9a048e
-  data.tar.gz: 33311be1f0d80a9ff3fd613acd21a02e0535945271e08af9cdf4b83d1021310479681bb7f07e8acb36663654d130fa29c635dcf796b1489cb9fbeec73d1f9a25
+  metadata.gz: 9ada037d0a4b3ddc819067452b0688e027df4ffdc2378de1dcc96a509e1aa0243ce8f58e2d00b458861d6b15afc27d1e708a0f03181fbbfb2a016e5f4691c1be
+  data.tar.gz: 316571ca7aae8d6714b2998e8a78b15a76ba2de7eb6c6a638efcb7652db98ff59435a9b05146e74e406900c7639176557ee1912a36578eedc7b0109668ea086d

data/lib/withruntime/agents.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # An agent: +id+, +name+, +version+ (one more on each update), +definition+,
+  # +labels+, +created_at+, +updated_at+, and +warnings+, such as
+  # "subscription_for_customers" for an agent that serves your customers on a
+  # subscription login (an empty list when there are none).
+  class Agent < Record
+    def warnings = self["warnings"] || []
+  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+.
+  class AgentEvent < Record
+    def text = self["body"].is_a?(Hash) ? self["body"]["text"] : nil
+  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+
+  # (PermissionDeniedError).
+  #
+  #   definition = runtime.agents.templates.definition("claude-code", use: "team")
+  #   runtime.agents.create("reviewer", definition)
+  #   session = runtime.agents.start("reviewer", "Review the open pull requests.")
+  #   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),
+  # +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").
+  class Agents < Product
+    attr_reader :sessions, :triggers, :templates
+
+    def initialize(transport)
+      super
+      @sessions = AgentSessions.new(transport)
+      @triggers = AgentTriggers.new(transport)
+      @templates = AgentTemplates.new
+      # Approvals come later, here: agents.approvals.list / answer.
+    end
+
+    # Makes an agent at version 1. A name already used is a ConflictError
+    # (name_taken); the names sessions, triggers, templates and approvals are
+    # refused, since they are paths beside the agents.
+    def create(name, definition, labels: nil, idempotency_key: nil)
+      body = Fields.body(name: name, definition: AgentTemplates.plain(definition), labels: labels)
+      Agent.new(@t.json("POST", "/v1/agents", body: body, key: idempotency_key))
+    end
+
+    # By id or by name.
+    def get(agent) = Agent.new(@t.json("GET", "/v1/agents/#{seg(agent)}"))
+
+    # The first page of agents, at most +limit+ a page; +each+ walks every page.
+    def list(cursor: nil, limit: nil) = agents_page(cursor, limit)
+
+    # Replaces the whole definition: a new version. Sessions already running
+    # keep the version they started with.
+    def update(agent, definition)
+      body = { "definition" => Fields.convert(AgentTemplates.plain(definition)) }
+      Agent.new(@t.json("PATCH", "/v1/agents/#{seg(agent)}", body: body))
+    end
+
+    # Deletes an agent: its triggers go and its open sessions are asked to stop.
+    def delete(agent) = @t.json("DELETE", "/v1/agents/#{seg(agent)}") && nil
+
+    # Starts a session with +input+, its first words. With +key:+, your own
+    # 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).
+    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)
+      AgentSession.new(@t, answer["session"], joined: answer["joined"] == true, seq: answer["seq"])
+    end
+
+    private
+
+    def agents_page(cursor, limit)
+      body = @t.json("GET", "/v1/agents", query: { "cursor" => cursor, "limit" => limit })
+      Page.new(body["data"].map { |item| Agent.new(item) }, body["nextCursor"]) { |after| agents_page(after, limit) }
+    end
+  end
+
+  # +runtime.agents.sessions+: find sessions. A session is one piece of work
+  # or one conversation; it has its own sandbox while it runs.
+  class AgentSessions < Product
+    # A session to follow, send to, stop or wait for.
+    def get(id)
+      info = @t.json("GET", "/v1/agents/sessions/#{seg(id)}")
+      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.
+    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)
+    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) }
+    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.
+  class AgentSession
+    ENDED = %w[done failed stopped].freeze
+    # How long the API holds an events read open, and the margin past it a
+    # read waits for its answer.
+    POLL_SECONDS = 30
+    POLL_MARGIN = 15
+
+    attr_reader :info, :joined, :seq
+
+    def initialize(transport, info, joined: false, seq: nil)
+      @t = transport
+      @info = Record.new(info)
+      @joined = joined
+      @seq = seq
+    end
+
+    def id = @info["id"]
+    def state = @info["state"]
+    def joined? = @joined
+    def ended? = ENDED.include?(state)
+
+    # Reads the session again.
+    def refresh(timeout: nil)
+      @info = Record.new(@t.json("GET", path, timeout: timeout))
+      self
+    end
+
+    # 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
+    # Object#send stays as it is.
+    def send_message(text, idempotency_key: nil)
+      @t.json("POST", path("/messages"), body: { "text" => text }, key: idempotency_key)["seq"]
+    end
+
+    # The session's log after +after+ (0, the whole log), in order, each an
+    # AgentEvent; without a block, an Enumerator. It waits for new events and
+    # ends once the session has ended and its last event has been given.
+    def events(after: 0, &block)
+      return enum_for(:events, after: after) unless block
+
+      wait = POLL_SECONDS
+      loop do
+        page = read_events(after, wait)
+        data = page["data"] || []
+        data.each do |item|
+          event = AgentEvent.new(item)
+          after = event.seq
+          yield event
+        end
+        # Ended: read on at once, without waiting, until nothing is left.
+        if page["ended"]
+          return nil if wait.zero? && data.empty?
+
+          wait = 0
+        end
+      end
+    end
+
+    # 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: {}))
+    end
+
+    # The session once it has ended (done, failed or stopped); a failed
+    # session is returned, not raised. Waits on the server, with no polling.
+    # +timeout+ in seconds (nil or 0: no deadline) raises a ConnectionError
+    # with code "timeout" when it passes first.
+    def wait(timeout: nil)
+      deadline = timeout&.positive? ? now + timeout : nil
+      loop do
+        refresh(timeout: deadline && left(deadline))
+        return @info if ended?
+
+        loop do
+          seconds = deadline ? [POLL_SECONDS, left(deadline).ceil].min : POLL_SECONDS
+          page = read_events(@info["lastSeq"] || 0, seconds)
+          break if page["ended"] || !(page["data"] || []).empty?
+
+          left(deadline) if deadline
+        end
+      end
+    end
+
+    def inspect = "#<#{self.class.name} #{id} #{state}>"
+
+    private
+
+    def path(suffix = "") = "/v1/agents/sessions/#{Transport.segment(id)}#{suffix}"
+
+    # One long poll: its own deadline past the API's hold, whatever the client's.
+    def read_events(after, wait)
+      @t.json("GET", path("/events"), query: { "after" => after, "wait" => wait }, timeout: [@t.timeout, wait + POLL_MARGIN].max)
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def left(deadline)
+      seconds = deadline - now
+      raise @t.connection_error(true, false, nil) unless seconds.positive?
+
+      seconds
+    end
+  end
+
+  # +runtime.agents.triggers+: what starts or feeds an agent's sessions
+  # besides the API. A trigger is +id+, +agent_id+, +kind+, +config+,
+  # +paused_at+, +paused_why+ and +created_at+. The kinds and their configs:
+  #
+  #   slack     { team: "T…", channel: "C…" }, once Runtime's Slack app is installed
+  #   github    { repository: "owner/name", installation: <Runtime's GitHub App
+  #             installation id, the organization's own>, events: [...] (optional) }
+  #   schedule  { cron: "0 9 * * 1-5", timezone: "America/Denver" (optional), input: "words" }
+  #   webhook   {}
+  #
+  # A slack or github trigger whose app is not installed for the account is
+  # refused +not_installed+ (ConflictError).
+  class AgentTriggers < Product
+    def create(agent, kind, config = {})
+      Record.new(@t.json("POST", "/v1/agents/#{seg(agent)}/triggers", body: { "kind" => kind, "config" => Fields.convert(config.to_h) }))
+    end
+
+    def list(agent) = @t.json("GET", "/v1/agents/#{seg(agent)}/triggers")["data"].map { |row| Record.new(row) }
+
+    # Holds this trigger alone; its events are refused +trigger_paused+, with
+    # +why+, where they came from. Nothing else is held.
+    def pause(id, why) = Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/pause", body: { "why" => why }))
+
+    def resume(id) = Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/resume", body: {}))
+
+    def delete(id) = @t.json("DELETE", "/v1/agents/triggers/#{seg(id)}") && nil
+  end
+
+  # +runtime.agents.templates+: the five harnesses an agent can run, each
+  # usable for either use, and the two uses.
+  #
+  #   runtime.agents.templates.map(&:key)   # claude-code, codex, gemini-cli, claude-agent-sdk, openai-agents-sdk
+  #   runtime.agents.templates["codex"].api_key_secret
+  #   runtime.agents.templates.uses["support"].session_key
+  #   runtime.agents.templates.definition("claude-code", use: "support")
+  #
+  # A subscription is for your own team's agents. An agent that serves your
+  # customers (api or webhook sessions for end users) uses an API key: those
+  # are the providers' terms, and the API warns +subscription_for_customers+
+  # on an agent that does not.
+  class AgentTemplates
+    include Enumerable
+
+    # The same values as every Runtime SDK and the guide
+    # (packages/cloud-guide/agent-templates.json).
+    DATA = {
+      "templates" => {
+        "claude-code" => {
+          "key" => "claude-code",
+          "title" => "Claude Code",
+          "command" => "npx -y @anthropic-ai/claude-code --dangerously-skip-permissions --mcp-config ~/.runtime-agent/mcp.json -p \"$(cat ~/.runtime-agent/start.md)\"",
+          "apiKeySecret" => "ANTHROPIC_API_KEY",
+          "apiKeyHost" => "api.anthropic.com",
+          "subscription" => "token: run `claude setup-token` on your own computer (Pro/Max), then `runtime secrets set CLAUDE_CODE_OAUTH_TOKEN` scoped to api.anthropic.com",
+          "definition" => {
+            "command" => "npx -y @anthropic-ai/claude-code --dangerously-skip-permissions --mcp-config ~/.runtime-agent/mcp.json -p \"$(cat ~/.runtime-agent/start.md)\"",
+            "secrets" => ["ANTHROPIC_API_KEY"]
+          }
+        },
+        "codex" => {
+          "key" => "codex",
+          "title" => "Codex CLI",
+          "command" => "npx -y @openai/codex exec --dangerously-bypass-approvals-and-sandbox \"$(cat ~/.runtime-agent/start.md)\"",
+          "apiKeySecret" => "OPENAI_API_KEY",
+          "apiKeyHost" => "api.openai.com",
+          "subscription" => "login once in the sandbox's terminal: `npx -y @openai/codex login --device-auth`, kept in the snapshot or a volume at `~/.codex`",
+          "definition" => {
+            "command" => "npx -y @openai/codex exec --dangerously-bypass-approvals-and-sandbox \"$(cat ~/.runtime-agent/start.md)\"",
+            "secrets" => ["OPENAI_API_KEY"]
+          }
+        },
+        "gemini-cli" => {
+          "key" => "gemini-cli",
+          "title" => "Gemini CLI",
+          "command" => "npx -y @google/gemini-cli --yolo -p \"$(cat ~/.runtime-agent/start.md)\"",
+          "apiKeySecret" => "GEMINI_API_KEY",
+          "apiKeyHost" => "generativelanguage.googleapis.com",
+          "subscription" => "login once in the sandbox's terminal (Sign in with Google), kept at `~/.gemini`",
+          "definition" => {
+            "command" => "npx -y @google/gemini-cli --yolo -p \"$(cat ~/.runtime-agent/start.md)\"",
+            "secrets" => ["GEMINI_API_KEY"]
+          }
+        },
+        "claude-agent-sdk" => {
+          "key" => "claude-agent-sdk",
+          "title" => "Claude Agent SDK",
+          "command" => "python3 ~/agent.py",
+          "apiKeySecret" => "ANTHROPIC_API_KEY",
+          "apiKeyHost" => "api.anthropic.com",
+          "subscription" => nil,
+          "definition" => {
+            "command" => "python3 ~/agent.py",
+            "secrets" => ["ANTHROPIC_API_KEY"]
+          }
+        },
+        "openai-agents-sdk" => {
+          "key" => "openai-agents-sdk",
+          "title" => "OpenAI Agents SDK",
+          "command" => "python3 ~/agent.py",
+          "apiKeySecret" => "OPENAI_API_KEY",
+          "apiKeyHost" => "api.openai.com",
+          "subscription" => nil,
+          "definition" => {
+            "command" => "python3 ~/agent.py",
+            "secrets" => ["OPENAI_API_KEY"]
+          }
+        }
+      },
+      "uses" => {
+        "support" => {
+          "key" => "support",
+          "title" => "Your customers",
+          "sessionKey" => "customer:<id>",
+          "triggers" => %w[api webhook],
+          "definition" => {
+            "template" => "support",
+            "vcpu" => 1,
+            "memoryMiB" => 1024,
+            "idlePauseSeconds" => 10,
+            "maxConcurrent" => 1000
+          }
+        },
+        "team" => {
+          "key" => "team",
+          "title" => "Your team",
+          "sessionKey" => nil,
+          "triggers" => %w[slack github],
+          "definition" => {
+            "template" => "team",
+            "vcpu" => 4,
+            "memoryMiB" => 8192
+          }
+        }
+      }
+    }.then { |data| JSON.parse(JSON.generate(data), freeze: true) }
+
+    # A definition given as a Record (a template's own) as the Hash it holds.
+    def self.plain(definition) = definition.is_a?(Record) ? definition.to_h : definition
+
+    # The harness template +key+ (+key+, +title+, +command+, +api_key_secret+,
+    # +api_key_host+, +subscription+: how to log in on one, or nil, and
+    # +definition+), or nil.
+    def [](key) = DATA["templates"][key.to_s]&.then { |template| Record.new(template) }
+
+    def keys = DATA["templates"].keys
+
+    # The harness templates, in order.
+    def each(&block)
+      return enum_for(:each) unless block
+
+      DATA["templates"].each_value { |template| block.call(Record.new(template)) }
+    end
+
+    # The uses, "support" (your customers, driven by your own app: one session
+    # per end customer under your own key such as "customer:42", paused between
+    # their messages) and "team" (your team's
+    # code, from Slack and GitHub): +key+, +title+, +session_key+, +triggers+
+    # and the +definition+ preset merged over a template's.
+    def uses = DATA["uses"].transform_values { |use| Record.new(use) }
+
+    # A new definition: the template's, with the use's preset over it. Ready
+    # for +agents.create(name, definition)+. An unknown key raises
+    # InvalidRequestError before anything is sent.
+    def definition(template, use: nil)
+      found = DATA["templates"][template.to_s] or raise unknown("template", template, DATA["templates"].keys)
+      out = JSON.parse(JSON.generate(found["definition"]))
+      return out if use.nil?
+
+      preset = DATA["uses"][use.to_s] or raise unknown("use", use, DATA["uses"].keys)
+      out.merge(JSON.parse(JSON.generate(preset["definition"])))
+    end
+
+    # Every template and use as plain JSON data: { "templates" => ..., "uses" => ... }.
+    def to_h = JSON.parse(JSON.generate(DATA))
+
+    def inspect = "#<#{self.class.name} #{keys.join(", ")}; uses #{DATA["uses"].keys.join(", ")}>"
+
+    private
+
+    def unknown(what, value, known)
+      InvalidRequestError.new("No agent #{what} is called #{value.inspect}.", code: "invalid_request", status: 400,
+                                                                               hint: "One of: #{known.join(", ")}.")
+    end
+  end
+end

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

@@ -23,8 +23,9 @@ module WithRuntime
   RENAME_RETIRES = nil
 
   class Client
-    attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :limits, :referrals,
-                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp
+    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,
+                :apps, :functions, :builds
 
     # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
     # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
@@ -56,6 +57,7 @@ module WithRuntime
       @volumes = Volumes.new(@transport)
       @secrets = Secrets.new(@transport)
       @limits = Limits.new(@transport)
+      @emails = Emails.new(@transport)
       @referrals = Referrals.new(@transport)
       @switching = Switching.new(@transport)
       @events = Events.new(@transport)
@@ -70,6 +72,11 @@ module WithRuntime
       @networks = Networks.new(PrivateTunnel.new(@transport))
       @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)
     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/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|
@@ -88,12 +96,22 @@ 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.
-    def set(name, value:, hosts:, header: nil, format: nil)
-      body = { "value" => value, "hosts" => hosts, "header" => header, "format" => format }.compact
+    # {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
       Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}", body: body))
     end
 
+    # Changes which sandboxes get a secret, without its value: +{}+ is every sandbox of the
+    # organization again. Returns the secret, with +only+ and +enforced+.
+    def scope(name, only)
+      Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}/sandboxes", body: only))
+    end
+
     # Names, hosts and placeholders. Never values.
     def list = @t.json("GET", "/v1/egress-secrets")["secrets"].map { |secret| Record.new(secret) }
 
@@ -115,6 +133,21 @@ module WithRuntime
     def get = Record.new(@t.json("GET", "/v1/referrals"))
   end
 
+  # +runtime.emails+: which of Runtime's optional emails this key's person gets
+  # for this account: own-deletions (warnings for dates the account's own
+  # retention set), billing, usage and tips. Sign-in, support replies, credit
+  # expiry and deletions Runtime decides are always sent and are not listed.
+  class Emails < Product
+    def get = @t.json("GET", "/v1/account/emails")["settings"].map { |row| Record.new(row) }
+
+    # Turns one on or off for this key's person only, and answers all of them.
+    # Needs a key for every action.
+    def set(category, enabled)
+      body = { "category" => category, "enabled" => enabled }
+      @t.json("POST", "/v1/account/emails:update", body: body)["settings"].map { |row| Record.new(row) }
+    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/version.rb

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

data/lib/withruntime.rb

@@ -26,7 +26,10 @@ require_relative "withruntime/wallet"
 require_relative "withruntime/tar"
 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/network_products"
 require_relative "withruntime/parity_products"
 require_relative "withruntime/file_watch"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: withruntime
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Runtime
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 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,
@@ -20,7 +20,10 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - 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/credentials.rb
 - lib/withruntime/errors.rb