withruntime 0.6.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c855551b3670978d87aab0540d48736b4f9f0935cb8109cbb9a6bdbf85b05d96
-  data.tar.gz: c2e545740a78cc37fdcdec6de993c4b12402906f68a0bd3692d07f357bd17c4e
+  metadata.gz: dcc3df961b7af1a6f8c2941b1e829ce2e7b4f0e1dfcc8a57a5b32159c89996e7
+  data.tar.gz: e664bcedb285f6edda1adc3e5fd05fc5a4bd2b304e2e8d64d5dd46420128984f
 SHA512:
-  metadata.gz: 9ada037d0a4b3ddc819067452b0688e027df4ffdc2378de1dcc96a509e1aa0243ce8f58e2d00b458861d6b15afc27d1e708a0f03181fbbfb2a016e5f4691c1be
-  data.tar.gz: 316571ca7aae8d6714b2998e8a78b15a76ba2de7eb6c6a638efcb7652db98ff59435a9b05146e74e406900c7639176557ee1912a36578eedc7b0109668ea086d
+  metadata.gz: 28da69ad5124df7ff53dc9b2ce0d17b7bd3e9ef934512884433bfe1aea3fa0983b259ec5dc2ea50f2f9c138e19e8d296221ef6b895115762c13e5a69ef082d63
+  data.tar.gz: 5d468e2f92368d91bea955b684fffc05f8be9404aa54c3dae3434baa1e3882de718416ce341ea26a30a49966cf416d5f986a188ade46888971315018afc2ebf0

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

@@ -25,7 +25,7 @@ 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,
-                :apps, :functions, :builds
+                :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.
@@ -77,6 +77,7 @@ module WithRuntime
       @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/products.rb

@@ -112,6 +112,13 @@ module WithRuntime
       Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}/sandboxes", body: only))
     end
 
+    # Narrows +hosts:+ and/or +rules:+ without the value; only strictly narrower
+    # ones are accepted. Widening needs the value: call +set+ again with it.
+    def narrow(name, hosts: nil, rules: nil)
+      body = { "hosts" => hosts, "rules" => rules }.compact
+      Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}/rules", body: body))
+    end
+
     # Names, hosts and placeholders. Never values.
     def list = @t.json("GET", "/v1/egress-secrets")["secrets"].map { |secret| Record.new(secret) }
 

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.6.0"
+  VERSION = "0.9.0"
 end

data/lib/withruntime.rb

@@ -30,6 +30,7 @@ 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.6.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Runtime
@@ -25,6 +25,7 @@ files:
 - 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