pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/diagnostics.rb

@@ -0,0 +1,83 @@
+require "faraday"
+require "json"
+require "time"
+require_relative "errors"
+
+module PineSandbox
+  # Hash-compatible public payload with per-request scheduling metadata.
+  class DiagnosticResponse < Hash
+    attr_reader :retry_after
+
+    def initialize(payload, retry_after: nil)
+      super()
+      update(payload)
+      @retry_after = retry_after
+    end
+  end
+
+  # @api private — the Client exposes the project-scoped diagnostics operations.
+  class Diagnostics
+    def initialize(api_key:, zone:)
+      @api_key = api_key
+      @connection = zone.faraday(zone.control_host) do |f|
+        f.options.open_timeout = 5
+        f.options.timeout = 30
+      end
+    end
+
+    def create(computer_id:, idempotency_key:, session: nil, request_id: nil, description: nil)
+      body = { computer_id: computer_id, session: session, request_id: request_id, description: description }.compact
+      request(:post, "/v1/diagnostics", body: body, idempotency_key: idempotency_key)
+    end
+
+    def get(id)
+      raise ArgumentError, "valid diagnostic reference required" unless id.is_a?(String) && id.match?(/\Adiag_[0-9a-f]{16}\z/)
+
+      request(:get, "/v1/diagnostics/#{id}")
+    end
+
+    def inspect = "#<PineSandbox::Diagnostics [credentials redacted]>"
+    alias_method :to_s, :inspect
+
+    private
+
+    def request(method, path, body: nil, idempotency_key: nil)
+      op = "#{method.to_s.upcase} #{path}"
+      resp = @connection.public_send(method, path) do |req|
+        req.headers["Authorization"] = "Bearer #{@api_key}"
+        req.headers["Accept"] = "application/json"
+        req.headers["Idempotency-Key"] = idempotency_key if idempotency_key
+        if body
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+      end
+      result = JSON.parse(resp.body.to_s) rescue nil
+      result = {} unless result.is_a?(Hash)
+      request_id = resp.headers["x-request-id"] || result["request_id"]
+      retry_after = parse_retry_after(resp.headers["retry-after"])
+      unless (200..299).cover?(resp.status)
+        raise PortalError.new(result["detail"] || "Diagnostic request failed", status: resp.status,
+                              request_id: request_id, op: op, problem_type: result["type"], reason: result["reason"], retry_after: retry_after)
+      end
+      unless result["id"].is_a?(String) && result["id"].match?(/\Adiag_[0-9a-f]{16}\z/) && result["state"].is_a?(String) && !result["state"].empty?
+        raise PortalError.new("Invalid diagnostic response", status: resp.status, request_id: request_id, op: op, retry_after: retry_after)
+      end
+      DiagnosticResponse.new(result, retry_after: retry_after)
+    rescue Faraday::TimeoutError
+      raise PineSandbox::TimeoutError, PineSandbox.with_context("Diagnostic request timed out", op: op)
+    rescue Faraday::ConnectionFailed
+      raise PineSandbox::ConnectionError, PineSandbox.with_context("Diagnostic connection failed", op: op)
+    end
+
+    def parse_retry_after(value)
+      text = value.to_s.strip
+      return nil if text.empty?
+      return text.to_i if text.match?(/\A\d+\z/)
+
+      [(Time.httpdate(text) - Time.now).ceil, 0].max
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/pinesandbox/drive_mode.rb

@@ -0,0 +1,67 @@
+module PineSandbox
+  # session.drive.* — drive the session with your own agent. #observe is
+  # read-only (allowed even while Pine's agent runs — you can watch);
+  # #computer_use and #upload_file are mutating drive actions, refused while
+  # Pine's agent or a person is driving (a session has one driver at a time).
+  # The actions need the session token (ps_); #observe also accepts the
+  # Computer token, which a handle read without its ps_ uses.
+  #
+  # Reached via {Session#drive}: `session.drive.observe`.
+  class DriveMode
+    def initialize(session)
+      @session = session
+    end
+
+    # observe — the ObservationSnapshot: a screenshot plus the coordinate
+    # metadata (viewport / screenshot_size / device_scale_factor / scroll) and a
+    # monotonic seq + navigation page_epoch. Read-only.
+    def observe
+      coordinator.observe(token: @session.send(:read_token), name: name)
+    end
+
+    # computer_use(action, **fields) — one native computer-use action. `action`
+    # is e.g. :screenshot, :left_click, :type, :scroll; `fields` carry that
+    # action's inputs (coordinate:, text:, …). Returns the action result.
+    def computer_use(action, **fields)
+      coordinator.computer_use(token: ps, name: name, action: action.to_s, params: fields)
+    end
+
+    # The common actions, as #computer_use calls. Coordinates are screenshot
+    # pixels (see #observe for the mapping).
+    def screenshot = computer_use(:screenshot)
+    def click(x, y) = computer_use(:left_click, coordinate: [x, y])
+    def right_click(x, y) = computer_use(:right_click, coordinate: [x, y])
+    def double_click(x, y) = computer_use(:double_click, coordinate: [x, y])
+    def mouse_move(x, y) = computer_use(:mouse_move, coordinate: [x, y])
+    def type_text(text) = computer_use(:type, text: text)
+
+    # Presses a key or chord, such as "Enter" or "ctrl+a".
+    def key(chord) = computer_use(:key, text: chord)
+
+    # Scrolls at (x, y); direction is "up", "down", "left" or "right".
+    def scroll(x, y, direction, amount)
+      computer_use(:scroll, coordinate: [x, y], scroll_direction: direction.to_s, scroll_amount: amount)
+    end
+
+    # upload_file(selector, file) — set a previously-deposited attachment as the
+    # value of the file <input> matched by selector. `file` is a single
+    # name in the session's attachments/ (deposit it first via the files API).
+    def upload_file(selector, file)
+      coordinator.upload_file(token: ps, name: name, selector: selector, file: file)
+    end
+
+    private
+
+    def name
+      @session.name
+    end
+
+    def coordinator
+      @session.send(:coordinator)
+    end
+
+    def ps
+      @session.token
+    end
+  end
+end

data/lib/pinesandbox/error_taxonomy.rb

@@ -0,0 +1,104 @@
+module PineSandbox
+  # @api private — the retry judgment per problem type, used only when an
+  # older server omits `retryable` from a problem. A copy of
+  # sdks/pine-computer/contract/error-taxonomy.json, which the test suite
+  # checks this table against.
+  module ErrorTaxonomy
+    RETRYABLE_BY_PROBLEM_TYPE = {
+      "/errors/sandbox-not-found" => false,
+      "/errors/sandbox-not-ready" => true,
+      "/errors/unauthorized" => false,
+      "/errors/forbidden" => false,
+      "/errors/precondition-required" => false,
+      "/errors/precondition-failed" => true,
+      "/errors/malformed-json" => false,
+      "/errors/malformed-request" => false,
+      "/errors/invalid-field" => false,
+      "/errors/invalid-filename" => false,
+      "/errors/empty-patch" => false,
+      "/errors/actor-type-required" => false,
+      "/errors/invalid-transition" => false,
+      "/errors/control-not-held" => false,
+      "/errors/idempotency-in-progress" => true,
+      "/errors/lease-expired" => false,
+      "/errors/lease-refresh-unavailable" => true,
+      "/errors/session-not-found" => false,
+      "/errors/file-not-found" => false,
+      "/errors/session-busy" => true,
+      "/errors/agent-admission-unavailable" => true,
+      "/errors/session-limit" => false,
+      "/errors/session-teardown-failed" => true,
+      "/errors/desktop-bind-failed" => true,
+      "/errors/handoff-not-found" => false,
+      "/errors/handoff-unavailable" => true,
+      "/errors/handoff-expired" => false,
+      "/errors/handoff-not-human" => false,
+      "/errors/handoff-persistence-failed" => true,
+      "/errors/no-desktop-stream" => false,
+      "/errors/desktop-unavailable" => false,
+      "/errors/skills-unavailable" => false,
+      "/errors/secret-in-skill" => false,
+      "/errors/skill-author-failed" => true,
+      "/errors/author-in-flight" => true,
+      "/errors/author-not-found" => false,
+      "/errors/action-not-implemented" => false,
+      "/errors/computer-use-failed" => true,
+      "/errors/artifact-error" => true,
+      "/errors/artifact-not-found" => false,
+      "/errors/artifact-too-large" => false,
+      "/errors/capture-failed" => true,
+      "/errors/capture-not-enabled" => false,
+      "/errors/internal" => true,
+      "/errors/no-active-task" => false,
+      "/errors/no-active-turn" => false,
+      "/errors/no-pending-request" => false,
+      "/errors/stale-turn" => false,
+      "/errors/task-control-failed" => true,
+      "/errors/task-not-found" => false,
+      "/errors/task-not-ready" => true,
+      "/errors/bind-not-configured" => false,
+      "/errors/bind-lease-unenforceable" => false,
+      "/errors/bind-state-lost" => true,
+      "/errors/pod-tainted" => false,
+      "/errors/wrong-pod-uid" => false,
+      "/errors/stale-coord-boot-id" => false,
+      "/errors/already-bound-different-cid" => false,
+      "/errors/bind-in-progress" => true,
+      "/errors/egress-activation-failed" => true,
+      "/errors/bind-rejected" => false,
+      "/errors/bind-restore-failed" => true,
+      "/errors/hpke-decrypt-failed" => false,
+      "/errors/not-bound" => false,
+      "/errors/grant-cid-mismatch" => false,
+      "/errors/grant-downgrade" => false,
+      "/errors/grant-expired" => true,
+      "/errors/grant-hash-mismatch" => false,
+      "/errors/grant-malformed" => false,
+      "/errors/grant-refresh-rejected" => false,
+      "/errors/grant-wrong-cid" => false,
+      "/errors/bind-restore-no-challenge" => false,
+      "/errors/bind-restore-contended" => false,
+      "/errors/skill-publication-unavailable" => true,
+      "/errors/runtime-initializing" => true,
+      "/errors/computer-stopped" => false,
+      "/errors/stop-failed" => false,
+      "/errors/history-expired" => false,
+      "/errors/storage-exhausted" => false
+    }.freeze
+
+    module_function
+
+    # The taxonomy's verdict for a known type; otherwise 412 is retryable, 501
+    # is not, any other 5xx is, and everything else is not.
+    def retryable?(problem_type, status)
+      known = RETRYABLE_BY_PROBLEM_TYPE[problem_type.to_s]
+      return known unless known.nil?
+
+      status = status.to_i
+      return true if status == 412
+      return false if status == 501
+
+      status >= 500
+    end
+  end
+end