pinesandbox 0.3.18 → 0.3.20

data/lib/pinesandbox/session.rb

@@ -19,11 +19,17 @@ module PineSandbox
   # tabs, focus, epoch, drive actions, passkey intent and decisions) need the
   # session token.
   class Session
+    # What a session's agent may do with the Computer's artifacts
+    # (Computer#create_session `artifact_access:`).
+    ARTIFACT_ACCESS = %w[none read_only read_write].freeze
+
     attr_reader :info, :parent
 
-    def initialize(parent:, payload:)
+    # `artifact_access_known` is false when only the Computer knows the
+    # session's artifact access (Computer#adopt_session).
+    def initialize(parent:, payload:, artifact_access_known: true)
       @parent = parent
-      @info = Models::Session.from_payload(payload)
+      @info = Models::Session.from_payload(payload, artifact_access_known: artifact_access_known)
       raise PineSandbox::ApiError.new(status: 0, error_message: "empty session payload") if @info.nil?
     end
 
@@ -37,6 +43,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
@@ -49,6 +58,15 @@ module PineSandbox
       info.session_dir
     end
 
+    # What this session's agent may do with the Computer's artifacts, as set
+    # at create: "none", "read_only" or "read_write". "none" when the Computer
+    # doesn't say (an older one). nil for a session from
+    # Computer#adopt_session, whose access isn't known: read it with
+    # Computer#session(name).
+    def artifact_access
+      info.artifact_access
+    end
+
     # session.agent.* — hand-off-the-loop driving (run/steer/answer/cancel/reset/
     # status/result/events). The agent drives; you delegate goals. See {AgentMode}.
     def agent
@@ -286,6 +304,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 +335,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 +514,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) for a session an older SDK created as 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/streamed_read.rb

@@ -0,0 +1,80 @@
+require "tempfile"
+
+module PineSandbox
+  # @api private — what the SDK's streamed reads of a body share: a file read
+  # from a Computer (Adapters::CoordinatorAdapter) and an artifact read from
+  # storage (Artifacts). Only a 2xx body reaches the caller, chunk by chunk as
+  # it arrives; an error answer's body is kept, bounded, for its error.
+  module StreamedRead
+    # A failed answer keeps this much of its body for the error.
+    ERROR_BODY_CAP = 64 * 1024
+    # Chunk size for passing on a body that was spooled to a temp file.
+    SPOOL_READ_SIZE = 64 * 1024
+
+    # Raised through Faraday's read loop in place of an exception from the
+    # caller's block, so the block's own error is never mistaken for a
+    # dropped connection. The streaming method raises #error again as it was.
+    class BlockError < StandardError
+      attr_reader :error
+
+      def initialize(error)
+        @error = error
+        super(error.message)
+      end
+    end
+
+    module_function
+
+    # Calls the caller's block with `args` from inside Faraday's read loop,
+    # which would turn an IOError or EPIPE from the block into a dropped
+    # connection; the block's own error comes out as a BlockError.
+    def pass(block, *args)
+      block.call(*args)
+    rescue StandardError => e
+      raise BlockError.new(e)
+    end
+
+    # Adds as much of `chunk` to `buffer` as keeps it within ERROR_BODY_CAP.
+    def keep_error_body(buffer, chunk)
+      remaining = ERROR_BODY_CAP - buffer.bytesize
+      buffer << chunk.byteslice(0, remaining) if remaining.positive?
+    end
+
+    # Reads one streamed GET. Yields the proc to set as the request's
+    # on_data; the block sends the request and returns its response. Each
+    # chunk of a 2xx body goes to `deliver` with its answer (the Faraday env,
+    # or the response) as it arrives. faraday-net_http before 3.0 passes no
+    # env and learns the status only after the body, so its chunks go to a
+    # temp file, not memory, and on to `deliver` once the status is known. An
+    # error answer's body, kept up to ERROR_BODY_CAP, becomes the response's
+    # body. Returns the response.
+    def read(deliver)
+      error_body = +""
+      spool = nil
+      on_data = proc do |chunk, _received, env|
+        if env.nil?
+          (spool ||= Tempfile.new("pinesandbox-read", binmode: true)).write(chunk)
+        elsif env.status.to_i.between?(200, 299)
+          deliver.call(chunk.b, env) unless chunk.empty?
+        else
+          keep_error_body(error_body, chunk)
+        end
+      end
+      response = yield on_data
+      if spool
+        spool.rewind
+        if response.success?
+          while (chunk = spool.read(SPOOL_READ_SIZE))
+            deliver.call(chunk, response)
+          end
+        else
+          keep_error_body(error_body, spool.read(ERROR_BODY_CAP).to_s)
+        end
+      end
+      response.env.body = error_body if !response.success? && response.body.to_s.empty?
+      response
+    ensure
+      spool&.close!
+    end
+  end
+end

data/lib/pinesandbox/version.rb

@@ -1,3 +1,5 @@
 module PineSandbox
-  VERSION = "0.3.18"
+  VERSION = "0.3.20"
+  # What the SDK's requests send as User-Agent.
+  USER_AGENT = "pinesandbox-ruby/#{VERSION}".freeze
 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

@@ -8,6 +8,7 @@ require_relative "pinesandbox/models/computer_session"
 require_relative "pinesandbox/models/computer_tab"
 require_relative "pinesandbox/models/file_entry"
 require_relative "pinesandbox/models/artifact"
+require_relative "pinesandbox/models/artifact_file"
 require_relative "pinesandbox/sse_frame_parser"
 require_relative "pinesandbox/control_events"
 require_relative "pinesandbox/agent_events"
@@ -20,17 +21,18 @@ require_relative "pinesandbox/capture_keypair"
 require_relative "pinesandbox/adapters/coordinator_adapter"
 require_relative "pinesandbox/adapters/snapshot_adapter"
 require_relative "pinesandbox/skills"
+require_relative "pinesandbox/artifacts"
 require_relative "pinesandbox/author_terminal_translator"
 require_relative "pinesandbox/session"
 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.20
 platform: ruby
 authors:
 - Pine AI
@@ -117,6 +117,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - lib/pinesandbox.rb
@@ -125,6 +126,7 @@ files:
 - lib/pinesandbox/agent_events.rb
 - lib/pinesandbox/agent_mode.rb
 - lib/pinesandbox/agent_turn.rb
+- lib/pinesandbox/artifacts.rb
 - lib/pinesandbox/attach_credentials_source.rb
 - lib/pinesandbox/author_terminal_translator.rb
 - lib/pinesandbox/bind_hpke.rb
@@ -146,26 +148,29 @@ files:
 - lib/pinesandbox/errors.rb
 - lib/pinesandbox/exec_stream_parser.rb
 - lib/pinesandbox/models/artifact.rb
+- lib/pinesandbox/models/artifact_file.rb
 - lib/pinesandbox/models/computer_session.rb
 - lib/pinesandbox/models/computer_tab.rb
 - 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
 - lib/pinesandbox/sse_frame_parser.rb
 - lib/pinesandbox/state_hpke.rb
+- lib/pinesandbox/streamed_read.rb
 - 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 +179,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:
   - - ">="