pinesandbox 0.3.18 → 0.3.19

data/lib/pinesandbox/errors.rb

@@ -55,7 +55,7 @@ module PineSandbox
   # An HTTP error response from the Computer API. #status is the HTTP status;
   # #problem_type and #problem_extensions carry an RFC 9457 problem detail
   # (#field, #reason, #handoff_id, #request_id and #retryable? read its common
-  # members). The message is resource-first: the runtime (#runtime_id) and the
+  # members). The message is resource-first: the Computer sandbox (#sandbox_id) and the
   # operation (#op, "<METHOD> <path>") come before #request_id, so a handler
   # that logs only the message can still route a report.
   class ApiError < Error
@@ -73,14 +73,8 @@ module PineSandbox
       super(@built_message)
     end
 
-    # The runtime that answered, when the request reached one.
-    def runtime_id = problem_extensions["sandbox_id"]
-
-    # Deprecated: use #runtime_id.
-    def sandbox_id
-      PineSandbox.deprecated_name("ApiError#sandbox_id", "#runtime_id")
-      runtime_id
-    end
+    # The id of the Computer sandbox that answered, when the request reached a Computer.
+    def sandbox_id = problem_extensions["sandbox_id"]
 
     # The response's machine `code` ({code, message} bodies), when present.
     def code = error_code
@@ -105,12 +99,11 @@ module PineSandbox
     # The response's Retry-After in seconds, when it set one.
     attr_accessor :retry_after
 
-    # Folds the runtime and operation onto an error raised before they were
+    # Folds the sandbox id and operation onto an error raised before they were
     # known, filling only what the server didn't send, and rebuilds the message.
     # Returns self, for re-raising.
-    def attach_context!(runtime_id: nil, op: nil, sandbox_id: nil)
-      runtime_id ||= sandbox_id
-      problem_extensions["sandbox_id"] ||= runtime_id if runtime_id && !runtime_id.to_s.empty?
+    def attach_context!(sandbox_id: nil, op: nil)
+      problem_extensions["sandbox_id"] ||= sandbox_id if sandbox_id && !sandbox_id.to_s.empty?
       problem_extensions["op"] ||= op if op && !op.to_s.empty?
       @built_message = build_message
       self
@@ -131,7 +124,7 @@ module PineSandbox
           "API request failed with status #{status}"
         end
       parts = []
-      parts << "runtime=#{runtime_id}" if runtime_id && !runtime_id.to_s.empty?
+      parts << "sandbox=#{sandbox_id}" if sandbox_id && !sandbox_id.to_s.empty?
       parts << "op=#{op}" if op && !op.to_s.empty?
       parts << "request_id=#{request_id}" if request_id && !request_id.to_s.empty?
       parts.empty? ? base : "#{base} (#{parts.join(', ')})"
@@ -177,6 +170,10 @@ module PineSandbox
   # suspended or out of credits): control is cut, reads stay open. Re-attach,
   # or report the suspension.
   class LeaseExpired < ForbiddenError; end
+  # The project, or this Computer's binding, doesn't have a feature the call
+  # needs, such as the shell grant for Session#exec or the artifacts feature for
+  # the artifact methods. Retrying won't help.
+  class FeatureDisabled < ForbiddenError; end
   # The access lapsed and renewing it failed for now. Retry; don't re-attach.
   class LeaseRefreshUnavailable < ServiceUnavailableError; end
   class AnotherSessionHuman < ConflictError; end
@@ -198,6 +195,7 @@ module PineSandbox
   PROBLEM_TYPE_CLASSES = {
     "/errors/control-not-held" => ControlNotHeld,
     "/errors/lease-expired" => LeaseExpired,
+    "/errors/feature-disabled" => FeatureDisabled,
     "/errors/lease-refresh-unavailable" => LeaseRefreshUnavailable,
     "/errors/another-session-human" => AnotherSessionHuman,
     "/errors/concurrent-transition" => ConcurrentTransition,
@@ -230,20 +228,17 @@ module PineSandbox
   class ConnectionError < Error; end
   class ReadyTimeoutError < Error; end
 
-  # The runtime reported failed, terminated or unavailable before the
+  # The Computer reported failed, terminated or unavailable before the
   # lifecycle operation finished.
-  class RuntimeFailedError < Error
-    attr_reader :runtime_id, :state
+  class SandboxFailedError < Error
+    attr_reader :sandbox_id, :state
 
-    def initialize(message = nil, runtime_id: nil, state: nil)
-      @runtime_id = runtime_id
+    def initialize(message = nil, sandbox_id: nil, state: nil)
+      @sandbox_id = sandbox_id
       @state = state
-      super(message || "Computer runtime #{runtime_id} reported #{state.inspect} before completing the lifecycle operation")
+      super(message || "Computer sandbox #{sandbox_id} reported #{state.inspect} before completing the lifecycle operation")
     end
   end
-  # Deprecated: use RuntimeFailedError.
-  SandboxFailedError = RuntimeFailedError
-  deprecate_constant :SandboxFailedError
 
   class StreamError < Error; end
   class StreamingUnsupportedError < Error; end
@@ -295,14 +290,14 @@ module PineSandbox
     end
   end
 
-  # Start found an existing runtime. No replacement was allocated. Preserve the
-  # BindError superclass for integrations already rescuing Start conflicts.
-  class RuntimeRetainedError < BindError
-    attr_reader :runtime_id, :state
+  # Start found the Computer still running or paused, and started nothing.
+  # Preserve the BindError superclass for integrations already rescuing Start conflicts.
+  class SandboxRetainedError < BindError
+    attr_reader :sandbox_id, :state
 
-    def initialize(runtime_id:, state:)
-      @runtime_id, @state = runtime_id, state
-      super("Computer still has runtime #{runtime_id} (#{state}); Stop it or Resume retained memory before Start")
+    def initialize(sandbox_id:, state:)
+      @sandbox_id, @state = sandbox_id, state
+      super("Computer hasn't stopped (Computer sandbox #{sandbox_id}, state #{state}); Stop it or Resume retained memory before Start")
     end
   end
 
@@ -380,46 +375,34 @@ module PineSandbox
   class ProjectAccessDenied < AttachCredentialsError; end
 
   # 412 — another attach advanced the authorization revision. Terminal:
-  # reload/adopt the winning integrator database binding; do not allocate a runtime.
+  # reload/adopt the winning integrator database binding; do not start the Computer again.
   class BindingRevisionConflictError < AttachCredentialsError
-    attr_reader :current_binding_revision, :current_runtime_id
+    attr_reader :current_binding_revision, :current_sandbox_id
 
-    def initialize(message, current_binding_revision: nil, current_runtime_id: nil, current_sandbox_id: nil, **kwargs)
+    def initialize(message, current_binding_revision: nil, current_sandbox_id: nil, **kwargs)
       @current_binding_revision = current_binding_revision
-      @current_runtime_id = current_runtime_id || current_sandbox_id
+      @current_sandbox_id = current_sandbox_id
       super(message, **kwargs)
     end
 
     # The winning binding's revision (also #current_binding_revision).
     def current_revision = current_binding_revision
-
-    # Deprecated: use #current_runtime_id.
-    def current_sandbox_id
-      PineSandbox.deprecated_name("BindingRevisionConflictError#current_sandbox_id", "#current_runtime_id")
-      current_runtime_id
-    end
   end
 
   # Portal committed a new authorization revision, but the later bind
-  # failed. The SDK has cleaned up the fresh runtime best-effort. Persist the
+  # failed. The SDK has shut the Computer down best-effort. Persist the
   # revision before retrying so the next attach can supersede this attempt.
   # #credentials is present for create_computer, whose generated identity and
   # capture keypair would otherwise be lost because the method has no result.
   class AttachAuthorizationCommittedError < BindError
-    attr_reader :binding_revision, :runtime_id, :credentials
+    attr_reader :binding_revision, :sandbox_id, :credentials
 
-    def initialize(message, binding_revision:, runtime_id: nil, sandbox_id: nil, credentials: nil, **kwargs)
+    def initialize(message, binding_revision:, sandbox_id: nil, credentials: nil, **kwargs)
       @binding_revision = binding_revision
-      @runtime_id = runtime_id || sandbox_id
+      @sandbox_id = sandbox_id
       @credentials = credentials
       super(message, **kwargs)
     end
-
-    # Deprecated: use #runtime_id.
-    def sandbox_id
-      PineSandbox.deprecated_name("AttachAuthorizationCommittedError#sandbox_id", "#runtime_id")
-      runtime_id
-    end
   end
 
   # The Computer answered with an `X-Computer-Spec-Version` major this SDK
@@ -435,44 +418,44 @@ module PineSandbox
   end
 
   # The Computer rejected the portal-issued bind_token: bad signature, unknown
-  # kid, iss/aud mismatch, expired, replayed jti, or issued for another runtime.
+  # kid, iss/aud mismatch, expired, replayed jti, or issued for another start.
   # Terminal — retrying with the same token cannot succeed.
   class BindAuthError < BindError; end
 
-  # Another runtime holds the epoch lease for this Computer (a live attach
-  # exists elsewhere, or you are attaching from two places at once).
+  # This Computer is already attached elsewhere: another attach holds its epoch
+  # lease, or you are attaching from two places at once.
   class ComputerAlreadyAttachedError < BindError; end
 
-  # The allocated runtime can't be bound (it was already bound, or a prior
-  # bind failed on it). The SDK deletes it before raising; retry attach for a
-  # fresh runtime.
-  class RuntimeUnusableError < BindError; end
-  # Deprecated: use RuntimeUnusableError.
-  PodPoisonedError = RuntimeUnusableError
+  # This Computer sandbox can't be attached (it was already attached, or a prior attach
+  # failed on it). The SDK shuts it down before raising; retry attach to start
+  # the Computer again.
+  class SandboxUnusableError < BindError; end
+  # Deprecated: use SandboxUnusableError.
+  PodPoisonedError = SandboxUnusableError
   deprecate_constant :PodPoisonedError
 
-  # Saved state was unreachable during the bind; the runtime has been
-  # cleaned up. Retry attach later (transient).
+  # Saved state was unreachable during the bind; the SDK has shut the Computer
+  # down. Retry attach later (transient).
   class SavedStateUnavailableError < BindError; end
   # Deprecated: use SavedStateUnavailableError.
   BrokerUnreachableError = SavedStateUnavailableError
   deprecate_constant :BrokerUnreachableError
 
   # The bind handshake exhausted its retries without a terminal
-  # classification. Usually a runtime-allocation or network issue.
+  # classification. Usually a slow start or a network issue.
   class BindTimeoutError < BindError; end
 
   # The Computer returned 401 for its Computer token (ct_) — a REPORT that
   # it did not recognize the binding's token, NOT an instruction to
-  # re-attach. ct_ is binding-lifetime (no idle expiry), so on a live,
-  # current runtime this state is binding_auth_lost: surface it and
-  # reconcile; only confirmed runtime-gone evidence justifies an attach
-  # (a fresh runtime invalidates every ps_ and fences the old runtime's state).
+  # re-attach. ct_ is binding-lifetime (no idle expiry), so on a running
+  # Computer this state is binding_auth_lost: surface it and reconcile; only
+  # a Computer confirmed stopped justifies an attach (a new start invalidates
+  # every ps_ and fences the previous start's state).
   # A 401 for a session token (ps_) is an ordinary UnauthorizedError.
   class TokenRejectedError < BindError
-    MESSAGE = "the Computer rejected the computer token (401). ct_ is binding-lifetime, so on a live " \
-              "current runtime this is binding_auth_lost — reconcile; re-attach ONLY on confirmed " \
-              "runtime-gone evidence (a fresh runtime invalidates every ps_)".freeze
+    MESSAGE = "the Computer rejected the computer token (401). ct_ is binding-lifetime, so on a " \
+              "running Computer this is binding_auth_lost — reconcile; re-attach ONLY once the " \
+              "Computer is confirmed stopped (a new start invalidates every ps_)".freeze
 
     # The rejection of `api_error` (a 401 answer to a Computer token), with
     # its operation and request id folded into the message.
@@ -482,14 +465,14 @@ module PineSandbox
     end
   end
 
-  # The gateway can no longer route this Computer's attached runtime. This is
-  # distinct from an /errors/session-not-found response on a live
+  # The gateway can no longer route to this Computer's host, which is also
+  # true while it's paused or recovering. This is distinct from an /errors/session-not-found response on a live
   # Computer. Inherit the legacy 404 tier so existing NotFoundError rescues
   # remain valid; the original typed ApiError is retained as Exception#cause.
-  class RuntimeGoneError < NotFoundError
+  class SandboxGoneError < NotFoundError
     def initialize(api_error)
       detail = api_error.error_message.to_s
-      message = "the attached runtime is gone"
+      message = "the Computer can't be reached at its host"
       message = "#{message}: #{detail}" unless detail.empty?
       super(
         status: api_error.status,
@@ -502,9 +485,6 @@ module PineSandbox
       self.retry_after = api_error.retry_after
     end
   end
-  # Deprecated: use RuntimeGoneError.
-  SandboxGoneError = RuntimeGoneError
-  deprecate_constant :SandboxGoneError
 
   # 429 COMPUTER_CAPACITY_EXCEEDED on create/attach: the project is at its
   # concurrent Computer limit, so nothing was provisioned. Not retried by the

data/lib/pinesandbox/models/artifact.rb

@@ -3,7 +3,7 @@ require "time"
 module PineSandbox
   module Models
     # A session artifact's metadata — a managed session output (a client upload,
-    # a claimed browser download, or an agent task output) with a download
+    # a browser download, or an agent task output) with a download
     # endpoint. Returned by {PineSandbox::Session#list_artifacts} and
     # {PineSandbox::Session#upload_artifact}. Mirrors the spec `Artifact` schema.
     Artifact = Struct.new(

data/lib/pinesandbox/operations.rb

@@ -34,7 +34,6 @@ module PineSandbox
       ["cancelAgentV2", "POST", "/v2/sessions/{name}/agent/cancel", :computer, true, false],
       ["cancelAuthorRun", "POST", "/v2/sessions/{name}/skills/author/{author_id}/cancel", :computer, false, false],
       ["captureCheckpoint", "POST", "/v1/coord/capture", :computer, false, false],
-      ["claimDownloadOrphan", "POST", "/downloads/orphans/{guid}/claim", :computer, false, false],
       ["computerUse", "POST", "/v1/sessions/{name}/computer-use", :computer, false, false],
       ["createComputer", "POST", "/computer-sandboxes", :control, true, false],
       ["createDiagnostic", "POST", "/v1/diagnostics", :control, true, true],
@@ -49,7 +48,6 @@ module PineSandbox
       ["deleteSession", "DELETE", "/sessions/{name}", :computer, true, false],
       ["deleteSkillVersion", "DELETE", "/v1/skills/{name}/versions/{version}", :computer, true, false],
       ["destroyComputer", "DELETE", "/sandboxes/{sandboxId}", :control, true, false],
-      ["discardDownloadOrphan", "DELETE", "/downloads/orphans/{guid}", :computer, true, false],
       ["getAgentEventsPageV2", "GET", "/v2/sessions/{name}/agent/events/page", :computer, true, false],
       ["getAgentEventsV2", "GET", "/v2/sessions/{name}/agent/events", :computer, true, false],
       ["getAgentTurnV2", "GET", "/v2/sessions/{name}/agent/turns/{turn_id}", :computer, true, false],
@@ -74,7 +72,6 @@ module PineSandbox
       ["listAllSkillVersions", "GET", "/v1/skills/versions", :computer, true, false],
       ["listArtifacts", "GET", "/v1/sessions/{name}/artifacts", :computer, true, false],
       ["listAvailableLocations", "GET", "/v1/locations", :control, true, false],
-      ["listDownloadOrphans", "GET", "/downloads/orphans", :computer, true, false],
       ["listHandoffs", "GET", "/v1/sessions/{name}/handoffs", :computer, true, false],
       ["listOrphans", "GET", "/orphans", :computer, true, false],
       ["listPasskeyCeremonies", "GET", "/v1/passkeys/ceremonies", :computer, true, false],

data/lib/pinesandbox/{runtime_details.rb → sandbox_details.rb}

@@ -1,6 +1,6 @@
 module PineSandbox
-  # An observation of one runtime, not the identity or a cached health verdict.
-  RuntimeLifetime = Data.define(:idle_timeout_seconds, :min_idle_timeout_seconds,
+  # An observation of the started Computer, not its identity or a cached health verdict.
+  SandboxLifetime = Data.define(:idle_timeout_seconds, :min_idle_timeout_seconds,
                                 :max_idle_timeout_seconds, :max_runtime_age_seconds,
                                 :stop_at, :deadline) do
     def self.from_payload(value)
@@ -14,9 +14,9 @@ module PineSandbox
     end
   end
 
-  RuntimeDetails = Data.define(:id, :state, :reason, :message, :retryable,
+  SandboxDetails = Data.define(:id, :state, :reason, :message, :retryable,
                               :operation_id, :created_at, :expires_at, :lifecycle, :runtime_revision) do
-    def self.from_runtime(info)
+    def self.from_info(info)
       new(id: info.id, state: info.status, reason: info.reason, message: info.message,
           retryable: info.retryable, operation_id: info.operation_id,
           created_at: info.created_at, expires_at: info.expires_at, lifecycle: info.lifecycle, runtime_revision: info.runtime_revision)

data/lib/pinesandbox/{runtime_handle.rb → sandbox_handle.rb}

@@ -3,26 +3,25 @@ require_relative "errors"
 require_relative "clock"
 
 module PineSandbox
-  # Lifecycle handle for a Computer's runtime, backed by the project-scoped
+  # Lifecycle handle for a Computer sandbox, backed by the project-scoped
   # ControlPlane. A powered-on Computer holds one of these;
   # Computer#stop/#kill/#alive? delegate here. It carries NO data-plane knowledge —
   # the coordinator host is derived separately from the Zone.
   # @api private
-  class RuntimeHandle
+  class SandboxHandle
     READY = :running
     WAIT_FAILURE_STATES = %i[failed terminated unavailable].freeze
     LIVE = %i[running pending stopping].freeze
     DEFAULT_POLL_INTERVAL = 2
 
     attr_reader :id
-    alias_method :runtime_id, :id
+    alias_method :sandbox_id, :id
 
     # `clock` returns monotonic seconds and `sleeper` waits; both default to
-    # the control plane's clock. `sandbox_id:` is the deprecated spelling of
-    # `runtime_id:`.
-    def initialize(control_plane:, runtime_id: nil, sandbox_id: nil, status: nil, clock: nil, sleeper: nil)
-      id = runtime_id || sandbox_id
-      raise ArgumentError, "runtime_id required" if id.to_s.empty?
+    # the control plane's clock.
+    def initialize(control_plane:, sandbox_id: nil, status: nil, clock: nil, sleeper: nil)
+      id = sandbox_id
+      raise ArgumentError, "sandbox_id required" if id.to_s.empty?
 
       source = control_plane.respond_to?(:clock) ? control_plane.clock : PineSandbox::SYSTEM_CLOCK
       @control_plane = control_plane
@@ -53,13 +52,13 @@ module PineSandbox
     end
 
     def set_idle_timeout(seconds:)
-      observed = runtime_details
-      raise BindError, "Runtime has no admitted lifetime policy; choose idle timeout on the next Start" unless observed.lifecycle
+      observed = sandbox_details
+      raise BindError, "Computer was started without a lifetime policy; choose the idle timeout on the next Start" unless observed.lifecycle
 
       @control_plane.set_idle_timeout(@id, seconds: seconds, etag: observed.etag)
     end
 
-    def runtime_details
+    def sandbox_details
       @control_plane.get(@id)
     end
 
@@ -101,11 +100,11 @@ module PineSandbox
 
     # Explicit saved-state recovery discards retained memory. It is allowed
     # only after a recorded failure and is fenced by the observed HTTP ETag.
-    def release_failed_runtime(info, wait_timeout: 90, interval: DEFAULT_POLL_INTERVAL)
+    def release_failed_sandbox(info, wait_timeout: 90, interval: DEFAULT_POLL_INTERVAL)
       deadline = @clock.call + wait_timeout
       unless info.status == :stopping
         unless %i[save_failed unavailable failed terminated].include?(info.status) && info.reason != "CaptureTimeout"
-          raise PineSandbox::ConflictError.new(status: 409, error_message: "Runtime has no recorded failure; use Stop or Resume")
+          raise PineSandbox::ConflictError.new(status: 409, error_message: "The Computer has no recorded failure; use Stop or Resume")
         end
         raise PineSandbox::Error, "Server did not supply a conditional release version" if info.etag.to_s.empty?
         @control_plane.destroy(@id, if_match: info.etag, request_timeout: remaining(deadline))
@@ -229,8 +228,8 @@ module PineSandbox
         end
         return self if state == target
         if WAIT_FAILURE_STATES.include?(state)
-          raise PineSandbox::RuntimeFailedError.new(
-            "Computer runtime #{@id} reported #{state.inspect} before reaching #{target}", runtime_id: @id, state: state
+          raise PineSandbox::SandboxFailedError.new(
+            "Computer sandbox #{@id} reported #{state.inspect} before reaching #{target}", sandbox_id: @id, state: state
           )
         end
       end
@@ -245,8 +244,4 @@ module PineSandbox
     end
 
   end
-
-  # Deprecated: use RuntimeHandle.
-  SandboxHandle = RuntimeHandle
-  deprecate_constant :SandboxHandle
 end

data/lib/pinesandbox/session.rb

@@ -37,6 +37,9 @@ module PineSandbox
       info.label
     end
 
+    # The session token (ps_). A session read with Computer#session or
+    # Computer#sessions has none: only Computer#create_session returns it, so
+    # save it then.
     def token
       info.token
     end
@@ -286,6 +289,23 @@ module PineSandbox
       read_call { |read| coordinator.read_file(token: read, name: name, path: path, &block) }
     end
 
+    # A workdir file's bytes as a stream, for copying a large file onward
+    # without buffering it, such as a file a turn's result names: yields binary
+    # chunks as they arrive. Without a block, returns an Enumerator of the
+    # chunks that sends the request only when iterated
+    # (`session.open_file(path).each { |chunk| io.write(chunk) }`).
+    # An error answer raises before any chunk.
+    #
+    # @param path [String] workdir-relative file path.
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [nil, Enumerator]
+    def open_file(path, &block)
+      raise ArgumentError, "file path is required" if path.to_s.empty?
+      return enum_for(:open_file, path) unless block
+
+      read_call { |read| coordinator.read_file(token: read, name: name, path: path, &block) }
+    end
+
     # Deposits a material (an agent INPUT file) into the session's attachments/
     # root. `filename` is a single name — path separators ("/", "..") are
     # rejected. The attachments root is a SIBLING of the workdir that
@@ -300,7 +320,7 @@ module PineSandbox
       read_call { |read| coordinator.write_file(token: read, name: name, path: filename, content: content) }
     end
 
-    # Lists the session's artifacts — client uploads, claimed browser downloads,
+    # Lists the session's artifacts — client uploads, browser downloads,
     # and every completed turn's agent outputs (durably captured at each turn's
     # result). Newest-first.
     #
@@ -479,7 +499,7 @@ module PineSandbox
     # reach the browser. Driving needs control of the session, not this
     # token, so the same token serves a viewer and a driver. Re-mint before
     # each (re)connect. Returns { token:, expires_at: }. 409
-    # (NoDesktopStream) when the session has no browser; 503
+    # (NoDesktopStream) when the session is blind; 503
     # (DesktopUnavailable) when streaming is off.
     def desktop_token
       ct_call { coordinator.mint_desktop_token(token: parent.computer_token, name: name) }

data/lib/pinesandbox/spec_version_middleware.rb

@@ -5,7 +5,7 @@ module PineSandbox
   # Control-plane middleware: send the expected gateway generation and reject a
   # present, different response marker. Missing markers remain tolerated.
   # The gateway does not negotiate this request value, and its marker does not
-  # qualify a Computer runtime's agent protocol. Coordinator capability discovery
+  # qualify a Computer sandbox's agent protocol. Coordinator capability discovery
   # owns that check; this middleware is not installed on the Ruby data plane.
   class SpecVersionMiddleware < Faraday::Middleware
     REQUEST_HEADER = "Computer-Spec-Version".freeze

data/lib/pinesandbox/version.rb

@@ -1,3 +1,3 @@
 module PineSandbox
-  VERSION = "0.3.18"
+  VERSION = "0.3.19"
 end

data/lib/pinesandbox/zone.rb

@@ -11,7 +11,7 @@ module PineSandbox
   #                                                 endpoint; the gateway routes by path. The bare
   #                                                 <zone> host is the HUMAN portal — the SDK
   #                                                 never calls it.
-  #   data plane    : <runtime_id>.computer.<zone>  the Computer API + desktop stream, by path
+  #   data plane    : <sandbox_id>.computer.<zone>  the Computer API + desktop stream, by path
   #
   # `control_host` may be overridden (local/dev/private). `gateway_url` is for a caller inside the
   # gateway's own cluster: every connection then dials that URL and keeps its host as the Host header,
@@ -20,11 +20,8 @@ module PineSandbox
   # with an actionable message.
   class Zone
     ZONE_RE = /\A(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/
-    # The Computer host label (the runtime id): DNS-safe, <=63 chars.
-    RUNTIME_ID_RE = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
-    # Deprecated: use RUNTIME_ID_RE.
-    SANDBOX_ID_RE = RUNTIME_ID_RE
-    deprecate_constant :SANDBOX_ID_RE
+    # The Computer host label (the sandbox id): DNS-safe, <=63 chars.
+    SANDBOX_ID_RE = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
 
     attr_reader :zone, :gateway_url
 
@@ -106,8 +103,8 @@ module PineSandbox
     # subdomain selects the Computer, the PATH selects the role). For a `.localhost`
     # / `.lvh.me` zone there is no L7, so the host carries the local gateway's
     # high port — supplied by the caller as part of the zone string.
-    def data_host(runtime_id)
-      host = "#{validate_runtime_id(runtime_id)}.computer.#{@zone}"
+    def data_host(sandbox_id)
+      host = "#{validate_sandbox_id(sandbox_id)}.computer.#{@zone}"
       secure? ? host : "#{host}:#{@data_port}"
     end
 
@@ -161,10 +158,10 @@ module PineSandbox
       n
     end
 
-    def validate_runtime_id(id)
+    def validate_sandbox_id(id)
       s = id.to_s
-      unless s.length <= 63 && s.match?(RUNTIME_ID_RE)
-        raise ArgumentError, "invalid runtime id #{id.inspect}: must be a DNS-safe label (<=63 chars, lowercase [a-z0-9-], no leading/trailing/double hyphen)"
+      unless s.length <= 63 && s.match?(SANDBOX_ID_RE)
+        raise ArgumentError, "invalid sandbox id #{id.inspect}: must be a DNS-safe label (<=63 chars, lowercase [a-z0-9-], no leading/trailing/double hyphen)"
       end
       s
     end

data/lib/pinesandbox.rb

@@ -26,11 +26,11 @@ require_relative "pinesandbox/control_token_source"
 require_relative "pinesandbox/attach_credentials_source"
 require_relative "pinesandbox/spec_version_middleware"
 require_relative "pinesandbox/control_plane"
-require_relative "pinesandbox/runtime_handle"
+require_relative "pinesandbox/sandbox_handle"
 require_relative "pinesandbox/connection"
 require_relative "pinesandbox/computer"
 require_relative "pinesandbox/computer_binding"
-require_relative "pinesandbox/runtime_details"
+require_relative "pinesandbox/sandbox_details"
 require_relative "pinesandbox/client"
 
 # PineSandbox — the Pine Computer SDK. Create a Computer and attach to it with

data/pinesandbox.gemspec

@@ -10,13 +10,14 @@ Gem::Specification.new do |spec|
   spec.description = "Ruby SDK for Pine Computers: create a Computer for your project, attach to it, " \
                      "and drive its browser, desktop, shell and agent, with state that persists " \
                      "across stops and starts."
-  spec.homepage = "https://pinesandbox.io"
+  spec.homepage = "https://pinecomputer.io"
   spec.license = "Apache-2.0"
-  # SecureRandom.uuid_v7 (used for Computer ids) is Ruby 3.4+.
-  spec.required_ruby_version = ">= 3.4"
+  # SecureRandom.uuid_v7 (used for Computer ids) needs Ruby 3.3+.
+  spec.required_ruby_version = ">= 3.3"
 
   spec.metadata = {
     "homepage_uri" => spec.homepage,
+    "documentation_uri" => "https://console.pinecomputer.io/docs",
     "allowed_push_host" => "https://rubygems.org"
   }
 
@@ -24,6 +25,7 @@ Gem::Specification.new do |spec|
     `git ls-files -z`.split("\x0").select do |file|
       file.start_with?("lib/") || %w[
         Gemfile
+        LICENSE
         Rakefile
         README.md
         pinesandbox.gemspec

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinesandbox
 version: !ruby/object:Gem::Version
-  version: 0.3.18
+  version: 0.3.19
 platform: ruby
 authors:
 - Pine AI
@@ -117,6 +117,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - lib/pinesandbox.rb
@@ -151,8 +152,8 @@ files:
 - lib/pinesandbox/models/file_entry.rb
 - lib/pinesandbox/operations.rb
 - lib/pinesandbox/response_handler.rb
-- lib/pinesandbox/runtime_details.rb
-- lib/pinesandbox/runtime_handle.rb
+- lib/pinesandbox/sandbox_details.rb
+- lib/pinesandbox/sandbox_handle.rb
 - lib/pinesandbox/session.rb
 - lib/pinesandbox/skills.rb
 - lib/pinesandbox/spec_version_middleware.rb
@@ -161,11 +162,12 @@ files:
 - lib/pinesandbox/version.rb
 - lib/pinesandbox/zone.rb
 - pinesandbox.gemspec
-homepage: https://pinesandbox.io
+homepage: https://pinecomputer.io
 licenses:
 - Apache-2.0
 metadata:
-  homepage_uri: https://pinesandbox.io
+  homepage_uri: https://pinecomputer.io
+  documentation_uri: https://console.pinecomputer.io/docs
   allowed_push_host: https://rubygems.org
 rdoc_options: []
 require_paths:
@@ -174,7 +176,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="