pinesandbox 0.3.18 → 0.3.20

data/lib/pinesandbox/adapters/coordinator_adapter.rb

@@ -10,12 +10,15 @@ 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
     # @api private — the SDK's HTTP client for the Computer API, reached at the
-    # runtime's own host `https://<runtime_id>.computer.<zone>`. The subdomain
-    # selects the runtime and the PATH selects the role (the API at root);
+    # Computer sandbox's own host `https://<sandbox_id>.computer.<zone>`. The
+    # subdomain selects the Computer sandbox and the PATH selects the role (the
+    # API at root);
     # the host is port-less and header-less — no routing header.
     #
     # The bearer goes in `Authorization: Bearer`. The Computer gates every
@@ -34,26 +37,26 @@ 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
-
-      # The runtime is reached at its own host `https://<runtime_id>.computer.<zone>`
-      # (derived from `zone`), port-less and header-less: the subdomain selects the
-      # runtime and the PATH selects the role. `zone` is a PineSandbox::Zone.
-      # `host` is the per-runtime data-plane host `<runtime_id>.computer.<zone>`
+      # An event stream silent this long (three missed keepalives) is reopened.
+      STREAM_IDLE_TIMEOUT = 60
+
+      # The Computer sandbox is reached at its own host
+      # `https://<sandbox_id>.computer.<zone>` (derived from `zone`), port-less and
+      # header-less: the subdomain selects the Computer sandbox and the PATH
+      # selects the role. `zone` is a PineSandbox::Zone.
+      # `host` is the Computer sandbox's data-plane host `<sandbox_id>.computer.<zone>`
       # (scheme-less). `scheme` is http for a .localhost zone (local-dev loop),
       # https otherwise. `clock` paces retries and reconnects.
-      attr_reader :runtime_id, :host, :scheme, :clock
+      attr_reader :sandbox_id, :host, :scheme, :clock
 
       # discovery_token is the Computer token that reads the capability
       # manifest when a request's own token, such as a session's, cannot. An
       # adopted binding passes it; #bind records the one it issues.
-      # `sandbox_id:` is the deprecated spelling of `runtime_id:`.
-      def initialize(zone:, runtime_id: nil, sandbox_id: nil, discovery_token: nil, clock: PineSandbox::SYSTEM_CLOCK)
-        @runtime_id = runtime_id || sandbox_id
-        raise ArgumentError, "runtime_id required" if @runtime_id.to_s.empty?
+      def initialize(zone:, sandbox_id: nil, discovery_token: nil, clock: PineSandbox::SYSTEM_CLOCK)
+        @sandbox_id = sandbox_id
+        raise ArgumentError, "sandbox_id required" if @sandbox_id.to_s.empty?
 
-        @host = zone.data_host(@runtime_id)
+        @host = zone.data_host(@sandbox_id)
         @scheme = zone.http_scheme # http for a .localhost zone (local-dev loop), https otherwise
         @discovery_token = discovery_token
         @clock = clock
@@ -63,13 +66,7 @@ module PineSandbox
         @zone = zone
       end
 
-      # Deprecated: use #runtime_id.
-      def sandbox_id
-        PineSandbox.deprecated_name("CoordinatorAdapter#sandbox_id", "#runtime_id")
-        @runtime_id
-      end
-
-      # The full data-plane origin `<scheme>://<runtime_id>.computer.<zone>` — the
+      # The full data-plane origin `<scheme>://<sandbox_id>.computer.<zone>` — the
       # DelegatedConnection's `computer_host` is a complete URI per the Computer API,
       # so the web SDK derives the desktop's ws/wss scheme from it (no guessing).
       def base_url
@@ -77,7 +74,7 @@ module PineSandbox
       end
 
       # Bind handshake. Posts the portal-issued bind_token JWS to
-      # /v1/coord/bind and returns the runtime's `ct_` from the response.
+      # /v1/coord/bind and returns the Computer token (`ct_`) from the response.
       #
       # Auth model: bind_token's Ed25519 signature IS the auth — no
       # bearer token is presented here (the bind endpoint refuses
@@ -85,7 +82,7 @@ module PineSandbox
       #
       # @param bind_token [String] compact JWS Ed25519 token minted by the
       #   portal attach-credentials endpoint (AttachCredentialsSource).
-      # @param pod_uid [String] echoed runtime identity (must match the token).
+      # @param pod_uid [String] echoed Computer sandbox identity (must match the token).
       # @param coord_boot_id [String] echoed process boot id.
       # @param ciphertext [String] base64url HPKE wire (enc || aead_ct).
       # @return [Hash] { "computer_token" => ct_, "epoch" => Integer }.
@@ -109,7 +106,7 @@ module PineSandbox
       end
 
       # Fetches the Computer's per-process ephemeral HPKE public key and
-      # runtime identity. Public route — no token. The SDK seals the bind
+      # Computer sandbox identity. Public route — no token. The SDK seals the bind
       # payload to this key and echoes pod_uid/coord_boot_id back on bind.
       #
       # @return [Hash] { "pod_uid", "coord_boot_id", "ephem_pub_x25519"
@@ -192,31 +189,23 @@ module PineSandbox
         true
       end
 
-      # Orphan downloads: browser downloads no session owns (ct_ only).
-      def list_orphan_downloads(token:)
-        get("downloads/orphans", token: token).body
+      # 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 claim_orphan_download(token:, guid:, session_name:, filename: nil)
-        body = { session_name: session_name }
-        body[:filename] = filename if filename
-        post("downloads/orphans/#{escape(guid)}/claim", token: token, json: body).body
-      end
-
-      def discard_orphan_download(token:, guid:)
-        delete("downloads/orphans/#{escape(guid)}", token: token)
-        true
-      end
-
-      def create_session(token:, name: nil, label: nil, browser: false, blind: false)
+      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")
@@ -300,7 +289,7 @@ module PineSandbox
       # ----- Artifacts: list / read / zip / upload -----
 
       # GET /v1/sessions/{name}/artifacts?turn_id= — the session's artifacts
-      # (uploads + claimed downloads + every completed turn's durably-captured
+      # (uploads + browser downloads + every completed turn's durably-captured
       # agent outputs).
       def list_artifacts(token:, name:, turn_id: nil)
         route = "v1/sessions/#{escape(name)}/artifacts"
@@ -525,7 +514,7 @@ module PineSandbox
                   event.data["exitCode"] || event.data[:exitCode]
             exit_code = raw unless raw.nil?
           end
-          block.call(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
@@ -541,10 +530,16 @@ module PineSandbox
             req.headers["Accept"] = "text/event-stream"
             req.body = body.to_json
             req.options.on_data = proc do |chunk, _received, env|
-              if env.nil? || env.status.to_i.between?(200, 299)
+              if env.nil?
+                # faraday-net_http before 3.0 passes no env, so the status is
+                # known only at the end: parse the chunk and keep it in case
+                # the answer is an error.
+                parser.parse(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
@@ -568,6 +563,8 @@ module PineSandbox
         end
         ExecResult.new(stdout: stdout, stderr: stderr, exit_code: exit_code,
                        error_message: error_msg)
+      rescue BlockError => e
+        raise e.error
       end
 
       # Minimal struct surfaced by #exec. Matches the shape tests expect:
@@ -701,7 +698,7 @@ module PineSandbox
       end
 
       # Explicit qualification for a binding. No cache, downgrade or mutation.
-      # A missing discovery route is an old runtime; the gateway's typed
+      # A missing discovery route is an old Computer sandbox; the gateway's typed
       # sandbox-not-found response remains a lifecycle failure.
       def require_agent_protocol!(token:)
         manifest = capabilities(token: token)
@@ -709,7 +706,7 @@ module PineSandbox
 
         self
       rescue NotFoundError => e
-        raise if e.is_a?(RuntimeGoneError)
+        raise if e.is_a?(SandboxGoneError)
 
         raise AgentProtocolUnsupported
       end
@@ -899,10 +896,16 @@ module PineSandbox
           req.headers["Accept"] = "text/event-stream"
           req.headers["Last-Event-ID"] = last_event_id.to_s unless last_event_id.to_s.empty?
           req.options.on_data = proc do |chunk, _bytes, env|
-            if env.nil? || env.status.to_i.between?(200, 299)
+            if env.nil?
+              # faraday-net_http before 3.0 passes no env, so the status is
+              # known only at the end: parse the chunk and keep it in case the
+              # answer is an error.
+              parser.feed(chunk) { |frame| yield frame }
+              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
@@ -914,17 +917,7 @@ 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
 
       # The resuming event-stream engine. Each connection opens from the last
@@ -936,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
@@ -954,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
@@ -997,35 +986,26 @@ 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
       # raises, before any chunk. A transport fault after the first chunk
       # 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:)
-        error_body = +""
+      def stream_bytes(path, token:, accept:, &block)
         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.status.to_i.between?(200, 299)
-                yield chunk.b unless chunk.empty?
-              else
-                keep_error_body(error_body, chunk)
-              end
+          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
       end
 
       def get(path, token:, accept: "application/json", headers: nil)
@@ -1105,7 +1085,7 @@ module PineSandbox
       end
 
       def normalize_transport_fault(error, method, path)
-        suffix = context_suffix(@runtime_id, op_from_route(method, path), nil)
+        suffix = context_suffix(@sandbox_id, op_from_route(method, path), nil)
         if error.is_a?(Faraday::TimeoutError)
           PineSandbox::TimeoutError.new("Computer request timed out: #{error.message}#{suffix}")
         else
@@ -1123,7 +1103,7 @@ module PineSandbox
 
       # The coord route path on the gateway host. The gateway routes by subdomain
       # and selects the role by PATH, so the path is just the coord route — no
-      # proxy prefix, no runtime id, no port.
+      # proxy prefix, no sandbox id, no port.
       def route_path(suffix)
         "/#{suffix}"
       end
@@ -1151,12 +1131,12 @@ module PineSandbox
       def classify_failure!(response, token)
         check_success!(response)
       rescue NotFoundError => original
-        raise if original.is_a?(RuntimeGoneError) || !original.problem_type.to_s.empty?
+        raise if original.is_a?(SandboxGoneError) || !original.problem_type.to_s.empty?
 
-        # The session list is served by every live runtime, so an untyped 404
+        # The session list is served by every live Computer sandbox, so an untyped 404
         # there means the gateway no longer routes to it.
         operation = Operations.match(:computer, response.env.method.to_s.upcase, response.env.url.path)
-        raise RuntimeGoneError.new(original), cause: original if operation&.id == "listSessions"
+        raise SandboxGoneError.new(original), cause: original if operation&.id == "listSessions"
 
         # Healthy V2 calls need no discovery round trip. Qualify only an
         # ambiguous 404, without retrying the original operation.
@@ -1185,7 +1165,7 @@ module PineSandbox
         # edge / the ingress), fall back to the older shape so
         # existing callers that rescue ApiError / UnauthorizedError /
         # NotFoundError keep working unchanged.
-        # The RESOURCE spine for every error this adapter raises: WHICH Computer (@runtime_id,
+        # The RESOURCE spine for every error this adapter raises: WHICH Computer (@sandbox_id,
         # held by the adapter) and WHICH operation ("<METHOD> <path>", off the Faraday env). We
         # attach it to EVERY raised path so an integrator's generic handler sees the resource +
         # op with no extra plumbing. request_id is the secondary precision handle.
@@ -1200,9 +1180,9 @@ module PineSandbox
           begin
             raise_for_status!(response)
           rescue PineSandbox::ApiError => e
-            e.attach_context!(runtime_id: @runtime_id, op: op)
+            e.attach_context!(sandbox_id: @sandbox_id, op: op)
             if e.problem_type == "/errors/sandbox-not-found"
-              raise PineSandbox::RuntimeGoneError.new(e), cause: e
+              raise PineSandbox::SandboxGoneError.new(e), cause: e
             end
             raise
           end
@@ -1222,7 +1202,7 @@ module PineSandbox
         if response.status == 408 || response.status == 504
           message = parse_legacy_error_message(response.body)
           timeout = PineSandbox::TimeoutError.new(
-            "Computer request failed: status=#{response.status} message=#{message}#{context_suffix(@runtime_id, op, rid)}"
+            "Computer request failed: status=#{response.status} message=#{message}#{context_suffix(@sandbox_id, op, rid)}"
           )
           timeout.retry_after = retry_after_seconds(response)
           raise timeout
@@ -1240,7 +1220,7 @@ module PineSandbox
           else PineSandbox::ApiError
           end
         ext = {}
-        ext["sandbox_id"] = @runtime_id if @runtime_id && !@runtime_id.to_s.empty?
+        ext["sandbox_id"] = @sandbox_id if @sandbox_id && !@sandbox_id.to_s.empty?
         ext["op"] = op if op && !op.to_s.empty?
         ext["request_id"] = rid if rid
         raise klass.new(
@@ -1274,11 +1254,11 @@ module PineSandbox
       end
 
       # Resource-first troubleshooting suffix for the message-only error paths (TimeoutError
-      # has no problem_extensions): runtime (WHICH Computer runtime) → op (WHICH operation) →
+      # has no problem_extensions): sandbox (WHICH Computer sandbox) → op (WHICH operation) →
       # request_id. Each part only when present; "" when all absent.
-      def context_suffix(runtime_id, op, rid)
+      def context_suffix(sandbox_id, op, rid)
         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=#{rid}" if rid && !rid.to_s.empty?
         parts.empty? ? "" : " (#{parts.join(', ')})"
@@ -1297,39 +1277,35 @@ module PineSandbox
       end
 
       # Faraday connection to the Computer's gateway host. The base URL sets the
-      # Host (and TLS SNI) to `<runtime_id>.computer.<zone>` — covered by the
+      # Host (and TLS SNI) to `<sandbox_id>.computer.<zone>` — covered by the
       # gateway wildcard cert `*.computer.<zone>`. Port-less and header-less: the
       # gateway routes the subdomain to the pod and the PATH selects the role; no
       # 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
         end
       end
 
-      # Long-lived stream connection — disables the read timeout. The default
-      # `connection` above ships a 30s `options.timeout`; for SSE that's a
-      # papercut (a model-thinking turn or sparse control-event stream
-      # legitimately exceeds 30s of silence). Coord ships periodic `: ka`
-      # keepalive comments (every 20s) which reset Net::HTTP's read timer,
-      # so even with the default this rarely fires in practice — but the
-      # principled fix is to make the streaming socket actually long-lived.
+      # Long-lived stream connection. Its read timeout is an idle watchdog: coord
+      # sends a `: ka` keepalive comment every 20s, and each read resets the
+      # timer, so a quiet but healthy stream never trips it. A connection that
+      # sends nothing for STREAM_IDLE_TIMEOUT is half-open; the timeout raises
+      # Faraday::TimeoutError and follow_events reconnects from the cursor.
       #
-      # Faraday 2.x trap: `req.options.timeout = nil` does NOT mean "no
-      # timeout" on the Net::HTTP adapter. faraday-net_http 3.x only sets
-      # `http.read_timeout` when the option is truthy; nil falls through to
-      # Ruby's 60s default. The fix is to set it explicitly via the adapter
+      # Faraday 2.x trap: `req.options.timeout` is not honored the way it reads
+      # on the Net::HTTP adapter, so the read timeout is set in the adapter
       # 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|
-            http.read_timeout = nil
+            http.read_timeout = STREAM_IDLE_TIMEOUT
           end
         end
       end

data/lib/pinesandbox/agent_events.rb

@@ -165,11 +165,11 @@ module PineSandbox
     end
 
     # How the turn ended, including with a question (a `result` frame): the
-    # same Hash the turn's "result" holds, or nil for another event.
+    # same AgentResult the turn's #result returns, or nil for another event.
     def result
       return nil unless type == "result" && payload.is_a?(Hash)
 
-      payload
+      AgentResult.wrap(payload)
     end
 
     private

data/lib/pinesandbox/agent_turn.rb

@@ -1,6 +1,29 @@
 require "time"
 
 module PineSandbox
+  # How a turn ended (spec PublicTurnResult), from AgentTurn#result and
+  # AgentEvent#result: the result's own string-keyed Hash, extended with these
+  # readers. It stays a plain Hash, so a change to it is kept and YAML and JSON
+  # store it as they did before the readers existed. A frozen result can't be
+  # extended, so it reads as a frozen copy.
+  module AgentResult
+    def self.wrap(value)
+      return value unless value.is_a?(Hash)
+      return value if value.is_a?(self)
+      return value.dup.extend(self).freeze if value.frozen?
+
+      value.extend(self)
+    end
+
+    def terminal_reason = self["terminal_reason"]
+    # 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
+
   # One unit of agent work (spec PublicTurn), returned by AgentMode#run,
   # #wait, #answer, #steer and #cancel. A turn starts when a run or an answer is
   # accepted and ends when the agent finishes, fails, is canceled or asks a
@@ -25,8 +48,8 @@ module PineSandbox
     def state = self["state"]
     # The turn this turn's answer opened; present once it is "answered".
     def next_turn_id = self["next_turn_id"]
-    # How the turn ended, with "usage"; nil while it runs.
-    def result = self["result"]
+    # How the turn ended, an AgentResult with its usage; nil while it runs.
+    def result = AgentResult.wrap(self["result"])
     def first_event_id = self["first_event_id"]
     def last_event_id = self["last_event_id"]