withruntime 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53b4e63218b0587cacbd8e0ad8ec583ba4ce9b32ec0b792208b8f70750b5acd5
-  data.tar.gz: 3461a8000fc4817de3f06c6f6f40b6e5d29b49312a4e1f9c9dc94a649e91b8ae
+  metadata.gz: 32515cd23a35b91a06324a7af01623f6dd75015c116e041c499e7a9b9548609c
+  data.tar.gz: 67454492f534d850643392417477f3f3d2782e7564bebb43555f76c6a1c9adfa
 SHA512:
-  metadata.gz: b1bb2aea12c2959b3afcd694ad90124d1c04fcf60201fdece3f5f1264b40bfa3b3f8deec865c5265d806b6e8c389ebacfd4da833648133fdba93b9ece3d7352f
-  data.tar.gz: d0238775905bea2408a2d930a402f49a4001bf900c3a8c13acbd511aaf5c486b7b01da8b5f93dfc188e50b696e135b8b92dfd75a7f9c74f5d4dcbdfcce63b668
+  metadata.gz: 0ce1fea1e0289719efc5d1ece2a48181e8238a400c4abd25d3ed79c12661b6c28465acb33c43681f32dad71428c86a2bd94c11eae6692fbcc2d97e29d31c95c3
+  data.tar.gz: 07a2ef09506dd306e8843f1add75482ec75be67e696dcb3b9c66edec9d6b1540208914be83b2f165f89e92f9a54d3c4f27554d435b3ab74c8b5e7f2d67e0d866

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/client.rb

@@ -23,8 +23,8 @@ 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
 
     # +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 +56,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 +71,7 @@ module WithRuntime
       @networks = Networks.new(PrivateTunnel.new(@transport))
       @sso = SSO.new(@transport)
       @mcp = MCP.new(@transport)
+      @agents = Agents.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/products.rb

@@ -88,12 +88,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 +125,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/sandbox.rb

@@ -241,19 +241,20 @@ module WithRuntime
     # Runs a command and returns its exit code and output. A String runs under
     # +bash -c+; an Array runs the program directly, with no shell.
     #
-    # +cwd+ (default /workspace), +env+ (merged over the 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).
-    def exec(command, cwd: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
+    # +cwd+ (default /workspace), +user+ ("sandbox", the default, or "root",
+    # through the sandbox's passwordless sudo), +env+ (merged over the
+    # 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).
+    def exec(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
              check: false, idempotency_key: nil)
       streamed = on_stdout || on_stderr || (timeout && timeout > 60)
       result = if streamed
-                 collect(exec_stream(command, cwd: cwd, env: env, stdin: stdin, timeout: timeout,
+                 collect(exec_stream(command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
                                               idempotency_key: idempotency_key), on_stdout, on_stderr)
                else
-                 body = command_body(command, cwd, env, stdin, timeout)
+                 body = command_body(command, cwd, env, stdin, timeout, user)
                  CommandResult.new(@t.json("POST", path(":exec"), body: body, key: idempotency_key,
                                                                   timeout: timeout && (timeout + 60)))
                end
@@ -265,14 +266,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, 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, &block)
       unless block
-        return enum_for(:exec_stream, command, cwd: cwd, env: env, stdin: stdin, timeout: timeout,
+        return enum_for(:exec_stream, command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
                                                idempotency_key: idempotency_key)
       end
 
       longest = ApiDefaults::STREAMED_EXEC_TIMEOUT_SECONDS
-      body = command_body(command, cwd, env, stdin, timeout || longest).merge("stream" => true)
+      body = command_body(command, cwd, env, stdin, timeout || longest, user).merge("stream" => true)
       handed_over = nil
       process_id = nil
       cursor = 0
@@ -361,8 +362,8 @@ module WithRuntime
     # 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, 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)
+    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)
       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))
@@ -385,9 +386,10 @@ module WithRuntime
 
     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)
+    def command_body(command, cwd, env, stdin, timeout, user)
       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

data/lib/withruntime/version.rb

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

data/lib/withruntime.rb

@@ -26,6 +26,7 @@ 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/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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Runtime
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 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,6 +20,7 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - lib/withruntime.rb
+- lib/withruntime/agents.rb
 - lib/withruntime/api_defaults.rb
 - lib/withruntime/client.rb
 - lib/withruntime/credentials.rb