pinesandbox 0.3.19 → 0.3.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42cf362beb935ed10df113f8dae0e006d141ab3849f3203630fa0aad880a4616
-  data.tar.gz: '09865bf5bd34bfb3dcd6b3832ff8dcd69e992e2fa9b485215525b154567b9528'
+  metadata.gz: 1a5f2719e33f58ee6f18cfb781c42c983341981c5dc3c0469a71bfcdebe89b27
+  data.tar.gz: 3ef413fba3327ecfca7069f39f96241f622ccdccb795fec799b036b2f4931fa4
 SHA512:
-  metadata.gz: 5b62511ef3c2399f26d15d0372d9707534e06df49f615410b08f68493ccd290bf819d497b294aa49004b70741a4f2e607506acab686cb2cf4a429eb61c75dffe
-  data.tar.gz: b12ea12e14b46c4ebb078d690e2df1045da8e846548a06518806c0ea8ee5ce0b7d3e9d509662095781e27adb341b9591927f2cd9cb5846684c0db0cda56aeac0
+  metadata.gz: 715dfedf0fa03c0ed77ecf2fd5661f7ad060e1dc2d4a648499041290c0e060f98a9fad2d5fe63e3aec387f5134aeadca99558bde55be1482d06a4eb8c97caf64
+  data.tar.gz: 4356c0f100f12b2686517d54a656e4df7ee66a075476a9b2a80e37cd648ec5ddc2e2e1ba512eaee586a0653cc2291d0c77579d7b64f02cc93ea234f98ec21531

data/README.md

@@ -47,7 +47,7 @@ store.save_credentials(credentials.id, credentials.to_json)
 computer = client.create_computer(credentials)
 store.save_binding(computer.id, computer.binding.to_json)
 
-session = computer.create_session(browser: true) # Pine picks the name: save session.name
+session = computer.create_session # Pine picks the name: save session.name
 session.create_tab(url: "https://example.com")
 ```
 
@@ -227,17 +227,36 @@ For integrations using older storage or field-based methods:
 
 ## Sessions
 
-A session is the unit of work — a browser context + bash terminal. Create one, then
-drive it (next two sections). A Computer runs up to 3 sessions at once by default;
+A session is the unit of work: its own browser window and bash terminal. Create one,
+then drive it (next two sections). A Computer runs up to 3 sessions at once by default;
 `computer.capabilities` reports the limit (`sessions.concurrent`).
 
 ```ruby
-session = computer.create_session(name: "researcher-1", browser: true)
+session = computer.create_session(name: "researcher-1")
 computer.session("researcher-1")            # metadata by name; token is redacted
 computer.sessions                           # list all on this Computer
 computer.destroy_session("researcher-1")    # tear down (keeps on-disk dir; clean: true to GC)
 ```
 
+A session's agent can use the Computer's [artifacts](#artifacts) only when you create
+the session with `artifact_access: "read_only"` (list and read files) or
+`artifact_access: "read_write"` (also save and delete files and make public links).
+The default is `"none"`. `session.artifact_access` reports the access it was created
+with, and is `nil` for a session from `computer.adopt_session`, whose access only the
+Computer knows (`computer.session(name).artifact_access` reads it). Your own access
+with the project key, through `client.artifacts`, is the same either way.
+
+```ruby
+session = computer.create_session(name: "analyst", artifact_access: "read_only")
+session.artifact_access                     # => "read_only"
+```
+
+A person who must type a password or an MFA code takes control of the session
+(`session.take_control`, then `release_control`) and types it over the desktop while
+the agent waits. A secret your application already holds goes in the task instead
+(`session.agent.run(goal, secrets: {...})`): the agent reads it from
+`$SESSION_SECRETS`.
+
 ## Drive — Pine's agent (hand off the loop)
 
 For an attached Computer, `computer.require_agent_protocol!` checks public agent
@@ -427,6 +446,46 @@ Without a block, `open_file` returns an Enumerator of the chunks. Session files
 until the Computer stops; save what you need first. Routes: `/files` in the
 [Computer API reference](https://console.pinecomputer.io/spec/computer).
 
+## Artifacts
+
+A Computer's **artifacts** are the files it keeps beyond its sessions. Reach them
+with the project key, whether the Computer is running or stopped. A session's agent
+can use them only when the session was created with `artifact_access: "read_only"`
+or `"read_write"` (see [Sessions](#sessions)); that choice doesn't change your own
+access here.
+
+```ruby
+artifacts = client.artifacts(computer_id)
+
+page = artifacts.list(prefix: "research/")       # one page: files, folders, next_page_token
+page.files.each { |file| puts "#{file.path} #{file.size} #{file.note}" }
+
+artifacts.upload("inputs/brief.pdf", Pathname("brief.pdf"), note: "the brief")
+artifacts.upload("inputs/notes.txt", "plain bytes")
+artifacts.download("reports/q3.pdf", "q3.pdf")   # => bytes written
+artifacts.open("reports/q3.csv") { |chunk| io.write(chunk) }
+artifacts.copy(other_computer_id, "templates/form.pdf", "inputs/form.pdf")
+artifacts.delete("inputs/notes.txt")
+
+# A public link, served by the running Computer until it stops:
+computer.artifact_link("reports/q3.pdf", expires_in_seconds: 86_400)  # => { "url" => ..., "expires_at" => ... }
+```
+
+The SDK gets one short-lived storage token from Pine and sends the files straight to
+and from storage, never through Pine; it renews the token before it lapses. An upload
+takes a String of bytes, a `Pathname` or an IO with a known size, and resumes after a
+dropped connection; without `content_type:` it is typed by its path's extension, the
+same way in every Pine SDK. A download writes beside the destination and renames into
+place. `download` and `open` resume after a dropped connection, a request timeout, a
+429 or a 5xx other than 501, from where they stopped and from the same version of the
+file (one replaced meanwhile raises `PineSandbox::PreconditionFailedError`). `copy` also copies within the
+Computer, given its own id. A missing file raises `PineSandbox::ArtifactNotFoundError`
+(`#path`); while the Computer's artifacts are over their limit, `upload` and `copy`
+raise `PineSandbox::ArtifactStorageFullError` without sending anything, and check
+again on the next call, so deleting files makes room. `open` passes each chunk on as it
+arrives with faraday-net_http 3.0 or later; an older faraday-net_http gives the body
+only once it is complete, so `open` writes it to a temporary file first.
+
 ## Skills — `learn` / `teach` (and when each blocks)
 
 `session.learn` and `session.teach` author a learned-skill **draft** from
@@ -482,7 +541,7 @@ client.delete_computer(computer)  # PERMANENT: kill if attached, then delete id
 
 `stop` and `kill` keep the Computer's identity and saved state; `delete_computer`
 (a `Computer` or its id) ends both. The id is refused for every later attach, saved
-state is purged after 24 hours, and the id is never reusable. Deleting an unknown,
+state is purged after 25 hours, and the id is never reusable. Deleting an unknown,
 already-deleted, or other project's id also returns `true`. There is no undelete.
 
 `stop` submits graceful Stop to Pine's controller, then waits up to 390s

data/lib/pinesandbox/adapters/coordinator_adapter.rb

@@ -1,7 +1,6 @@
 require "faraday"
 require "json"
 require "securerandom"
-require "tempfile"
 require "uri"
 require_relative "../clock"
 require_relative "../errors"
@@ -11,6 +10,8 @@ require_relative "../control_events"
 require_relative "../sse_frame_parser"
 require_relative "../exec_stream_parser"
 require_relative "../response_handler"
+require_relative "../streamed_read"
+require_relative "../version"
 
 module PineSandbox
   module Adapters
@@ -36,10 +37,6 @@ module PineSandbox
 
       DEFAULT_HTTP_TIMEOUT = 30
       DEFAULT_OPEN_TIMEOUT = 5
-      # A non-2xx stream answer keeps this much of its body for the error.
-      STREAM_ERROR_BODY_CAP = 64 * 1024
-      # Chunk size for passing on a body that was spooled to a temp file.
-      SPOOL_READ_SIZE = 64 * 1024
       # An event stream silent this long (three missed keepalives) is reopened.
       STREAM_IDLE_TIMEOUT = 60
 
@@ -192,15 +189,23 @@ module PineSandbox
         true
       end
 
-      def create_session(token:, name: nil, label: nil, browser: false, blind: false)
+      # POST /v1/artifacts/links — a public link this running Computer serves
+      # to one of its artifacts (ct_ only). Returns { "url", "expires_at"? }.
+      def create_artifact_link(token:, path:, expires_in_seconds: nil)
+        body = { path: path }
+        body[:expires_in_seconds] = expires_in_seconds if expires_in_seconds
+        post("v1/artifacts/links", token: token, json: body).body
+      end
+
+      def create_session(token:, name: nil, label: nil, artifact_access: nil)
         # Omit :name when blank so the coordinator mints a friendly name; only
-        # send :label when the caller set one. Name stays first so the on-wire
-        # body order is stable.
+        # send :label and :artifact_access when the caller set them. Name stays
+        # first so the on-wire body order is stable. Every session has a
+        # browser window, so the request names none.
         body = {}
         body[:name] = name unless name.nil? || name.to_s.empty?
-        body[:browser] = browser
         body[:label] = label unless label.nil? || label.to_s.empty?
-        body[:blind] = true if blind
+        body[:artifact_access] = artifact_access if artifact_access
         post("sessions", token: token, json: body)
           .body
           .fetch("session")
@@ -509,7 +514,7 @@ module PineSandbox
                   event.data["exitCode"] || event.data[:exitCode]
             exit_code = raw unless raw.nil?
           end
-          pass_to_block(block, event) if block
+          StreamedRead.pass(block, event) if block
         end
         # Clamp the HTTP timeout above timeout_ms so the client waits for
         # the server's own timeout to fire an execution_complete event
@@ -530,11 +535,11 @@ module PineSandbox
                 # known only at the end: parse the chunk and keep it in case
                 # the answer is an error.
                 parser.parse(chunk)
-                keep_error_body(error_body, chunk)
+                StreamedRead.keep_error_body(error_body, chunk)
               elsif env.status.to_i.between?(200, 299)
                 parser.parse(chunk)
               else
-                keep_error_body(error_body, chunk)
+                StreamedRead.keep_error_body(error_body, chunk)
               end
             end
             req.options.timeout = http_timeout
@@ -896,11 +901,11 @@ module PineSandbox
               # known only at the end: parse the chunk and keep it in case the
               # answer is an error.
               parser.feed(chunk) { |frame| yield frame }
-              keep_error_body(error_body, chunk)
+              StreamedRead.keep_error_body(error_body, chunk)
             elsif env.status.to_i.between?(200, 299)
               parser.feed(chunk) { |frame| yield frame }
             else
-              keep_error_body(error_body, chunk)
+              StreamedRead.keep_error_body(error_body, chunk)
             end
           end
         end
@@ -912,29 +917,9 @@ module PineSandbox
         response
       end
 
-      # 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.
-      class BlockError < StandardError
-        attr_reader :error
-
-        def initialize(error)
-          @error = error
-          super(error.message)
-        end
-      end
+      BlockError = StreamedRead::BlockError
       private_constant :BlockError
 
-      # Runs the caller's block on one piece of a streamed answer from inside
-      # Faraday's read loop, which would turn an IOError or EPIPE from the
-      # block into a dropped connection. The streaming method raises the
-      # block's error again as it was.
-      def pass_to_block(block, value)
-        block.call(value)
-      rescue StandardError => e
-        raise BlockError.new(e)
-      end
-
       # The resuming event-stream engine. Each connection opens from the last
       # event id seen; frames advance the cursor before any decode, so a
       # skipped frame is never replayed. A dropped connection (a transport
@@ -944,7 +929,7 @@ module PineSandbox
       # dead one ends with StreamLostError. An error answer raises at once.
       # Returns the cursor when `terminal` or `stop_when` matches an event, or
       # when `max_reconnects` (a caller cap on total reconnects) is used up.
-      def follow_events(op:, cursor:, open:, decode:, terminal: nil, stop_when: nil, max_reconnects: nil)
+      def follow_events(op:, cursor:, open:, decode:, terminal: nil, stop_when: nil, max_reconnects: nil, &block)
         cursor = cursor.to_s
         failures = 0
         reconnects = 0
@@ -962,11 +947,7 @@ module PineSandbox
                 next if event.nil?
 
                 delivered = true
-                begin
-                  yield event
-                rescue StandardError => e
-                  raise BlockError.new(e)
-                end
+                StreamedRead.pass(block, event)
                 throw :pine_stream_stop if terminal&.call(event) || stop_when&.call(event)
               end
               request_id = request_id_header(response) || request_id
@@ -1005,11 +986,6 @@ module PineSandbox
         ::PineSandbox::ControlEvents.decode_event(frame.event, id, frame.data)
       end
 
-      def keep_error_body(buffer, chunk)
-        remaining = STREAM_ERROR_BODY_CAP - buffer.bytesize
-        buffer << chunk.byteslice(0, remaining) if remaining.positive?
-      end
-
       # Passes a binary GET's body to the block in chunks as it arrives instead
       # of buffering it. Only a 2xx body reaches the block: an error answer is
       # kept (bounded) and raised as the same typed error the buffered read
@@ -1017,44 +993,19 @@ module PineSandbox
       # raises too, so the caller knows the body is incomplete. The default
       # connection's read timeout bounds each wait for the next chunk.
       def stream_bytes(path, token:, accept:, &block)
-        error_body = +""
-        # faraday-net_http before 3.0 passes no env and learns the status only
-        # after the body, so a chunk can't be told from an error body until the
-        # response ends. Those chunks go to a temp file, not memory, and are
-        # passed on once the status is known.
-        spool = nil
         with_transport_norm("GET", path) do
-          response = connection.get(route_path(path)) do |req|
-            apply_token(req, token)
-            req.headers["Accept"] = accept
-            req.options.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)
-                pass_to_block(block, chunk.b) unless chunk.empty?
-              else
-                keep_error_body(error_body, chunk)
-              end
-            end
-          end
-          if spool
-            spool.rewind
-            if response.success?
-              while (chunk = spool.read(SPOOL_READ_SIZE))
-                yield chunk
-              end
-            else
-              keep_error_body(error_body, spool.read(STREAM_ERROR_BODY_CAP).to_s)
+          response = StreamedRead.read(->(chunk, _answer) { StreamedRead.pass(block, chunk) }) do |on_data|
+            connection.get(route_path(path)) do |req|
+              apply_token(req, token)
+              req.headers["Accept"] = accept
+              req.options.on_data = on_data
             end
           end
-          response.env.body = error_body if !response.success? && response.body.to_s.empty?
           ensure_success!(response, token: token) unless response.success?
         end
         nil
       rescue BlockError => e
         raise e.error
-      ensure
-        spool&.close!
       end
 
       def get(path, token:, accept: "application/json", headers: nil)
@@ -1332,7 +1283,7 @@ module PineSandbox
       # API key (coord gates every route on the bearer).
       def connection
         @connection ||= @zone.faraday(@host) do |conn|
-          conn.headers["User-Agent"] = "pinesandbox-ruby/#{PineSandbox::VERSION}"
+          conn.headers["User-Agent"] = PineSandbox::USER_AGENT
           conn.options.open_timeout = DEFAULT_OPEN_TIMEOUT
           conn.options.timeout = DEFAULT_HTTP_TIMEOUT
           conn.adapter Faraday.default_adapter
@@ -1350,7 +1301,7 @@ module PineSandbox
       # block, which the adapter calls AFTER applying request_timeout.
       def streaming_connection
         @streaming_connection ||= @zone.faraday(@host) do |conn|
-          conn.headers["User-Agent"] = "pinesandbox-ruby/#{PineSandbox::VERSION}"
+          conn.headers["User-Agent"] = PineSandbox::USER_AGENT
           conn.options.open_timeout = DEFAULT_OPEN_TIMEOUT
           # DELIBERATELY no conn.options.timeout — adapter block is authoritative.
           conn.adapter Faraday.default_adapter do |http|

data/lib/pinesandbox/agent_turn.rb

@@ -19,6 +19,7 @@ module PineSandbox
     # The agent's closing message; the question for "needs_input".
     def summary = self["summary"]
     def artifacts = self["artifacts"]
+    # Saved paths: client.artifacts(ref["computer_id"]).download(ref["path"], destination).
     def author = self["author"]
     def usage = self["usage"]
   end