pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/errors.rb

@@ -0,0 +1,525 @@
+require_relative "error_taxonomy"
+
+module PineSandbox
+  # Marks a renamed public method: the old name keeps working and, when Ruby's
+  # deprecation warnings are on (Warning[:deprecated] = true), warns once per
+  # call site with the name to use instead.
+  # @api private
+  def self.deprecated_name(old, new)
+    warn("PineSandbox: #{old} is deprecated; use #{new}", category: :deprecated, uplevel: 2)
+  end
+
+  # Fold a request_id INTO an error message string. The portal/Computer error classes
+  # below carry #request_id as an accessor, but integrators overwhelmingly log only
+  # `e.message` — so the one identifier that correlates a failure against the server's
+  # logs must land in the message too. No-op when there's no id (bind/connection faults
+  # that never reached a gateway-fronted response). ApiError folds its context the same way.
+  def self.with_request_id(message, request_id)
+    return message if request_id.to_s.empty?
+
+    "#{message} (request_id=#{request_id})"
+  end
+
+  # Fold the RESOURCE-FIRST troubleshooting context INTO an error message: op (WHICH
+  # operation — "<METHOD> <path>", carrying the computer/sandbox id where the call is
+  # resource-scoped, so it names WHICH resource) then request_id (the secondary precision
+  # handle). Each part only when present; no-op when both are absent. Integrators log only
+  # `e.message`, so a generic handler must see the operation without extra plumbing.
+  def self.with_context(message, op: nil, request_id: nil)
+    parts = []
+    parts << "op=#{op}" if op && !op.to_s.empty?
+    parts << "request_id=#{request_id}" if request_id && !request_id.to_s.empty?
+    parts.empty? ? message : "#{message} (#{parts.join(', ')})"
+  end
+
+  # Base for every error this SDK raises.
+  class Error < StandardError
+    # Set on a run's error when no response arrived (it is then also a
+    # RunUnconfirmedError): the run may have started. Send it again with this
+    # idempotency_key, which returns the turn it started, or starts it if it
+    # never did.
+    attr_accessor :idempotency_key
+  end
+
+  # Marks a run whose response never arrived, after the SDK resent it for as
+  # long as its budget allows: the run may have started. The error is still
+  # the failure that ended the resends (a ConnectionError, TimeoutError or
+  # ApiError, so existing rescues keep catching it), extended with this
+  # module, so `rescue PineSandbox::RunUnconfirmedError` catches it too. Send
+  # the run again with #idempotency_key, which returns the turn it started,
+  # or starts it if it never did.
+  module RunUnconfirmedError
+    def idempotency_key = @idempotency_key
+  end
+
+  # 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
+  # operation (#op, "<METHOD> <path>") come before #request_id, so a handler
+  # that logs only the message can still route a report.
+  class ApiError < Error
+    attr_reader :status, :error_code, :error_message, :response_body, :problem_type, :problem_extensions
+
+    def initialize(status:, error_code: nil, error_message: nil, response_body: nil,
+                   problem_type: nil, problem_extensions: nil)
+      @status = status
+      @error_code = error_code
+      @error_message = redact_credentials(error_message)
+      @response_body = redact_credentials(response_body)
+      @problem_type = problem_type
+      @problem_extensions = problem_extensions || {}
+      @built_message = build_message
+      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 response's machine `code` ({code, message} bodies), when present.
+    def code = error_code
+
+    def op = problem_extensions["op"]
+    def handoff_id = problem_extensions["handoff_id"]
+    def field = problem_extensions["field"]
+    def reason = problem_extensions["reason"]
+    def request_id = problem_extensions["request_id"]
+
+    # The server's verdict on whether retrying the same operation is sane.
+    # When the response doesn't say, the problem type's entry in the shared
+    # error taxonomy decides (412 and other 5xx true, 501 and the rest false).
+    # A true verdict never by itself makes a mutation safe to send again.
+    def retryable?
+      wire = problem_extensions["retryable"]
+      return wire if wire == true || wire == false
+
+      ErrorTaxonomy.retryable?(problem_type, status)
+    end
+
+    # 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
+    # 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?
+      problem_extensions["op"] ||= op if op && !op.to_s.empty?
+      @built_message = build_message
+      self
+    end
+
+    def message = @built_message
+    alias_method :to_s, :message
+
+    private
+
+    def build_message
+      base =
+        if error_message && !error_message.empty?
+          error_message
+        elsif error_code
+          "API request failed with status #{status} (#{error_code})"
+        else
+          "API request failed with status #{status}"
+        end
+      parts = []
+      parts << "runtime=#{runtime_id}" if runtime_id && !runtime_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(', ')})"
+    end
+
+    # A server can echo request headers into an error body, which becomes
+    # #response_body and, when it isn't JSON, the message. Callers log both, so a
+    # service credential never stays in either.
+    def redact_credentials(body)
+      return body unless body.is_a?(String)
+
+      body.gsub(/(X-EXECD-ACCESS-TOKEN["']?\s*[:=]\s*["']?)[^"'\s,}]+/i, '\1[REDACTED]')
+    end
+  end
+
+  # The Computer does not serve the public agent protocol. The SDK concludes it
+  # from capability discovery, so it has no HTTP status, and the request that
+  # led to discovery is not retried against an older protocol. This is not an
+  # API conflict and must never trigger conflict recovery or automatic steering.
+  class AgentProtocolUnsupported < Error
+    def initialize
+      super("This Computer does not support the required public agent protocol. Stop this Computer, then Start to update it.")
+    end
+  end
+
+  # Status tiers: rescue these whether or not the response named a problem type.
+  class BadRequestError < ApiError; end
+  class UnauthorizedError < ApiError; end
+  class ForbiddenError < ApiError; end
+  class NotFoundError < ApiError; end
+  class ConflictError < ApiError; end
+  class GoneError < ApiError; end
+  class PreconditionFailedError < ApiError; end
+  class UnprocessableEntityError < ApiError; end
+  class PreconditionRequiredError < ApiError; end
+  class ServerError < ApiError; end
+  class ServiceUnavailableError < ServerError; end
+
+  # Typed problem details, each under its status tier so tier rescues still
+  # catch them.
+  class ControlNotHeld < ConflictError; end
+  # The Computer's access lapsed and Pine refused to renew it (the project is
+  # suspended or out of credits): control is cut, reads stay open. Re-attach,
+  # or report the suspension.
+  class LeaseExpired < ForbiddenError; end
+  # The access lapsed and renewing it failed for now. Retry; don't re-attach.
+  class LeaseRefreshUnavailable < ServiceUnavailableError; end
+  class AnotherSessionHuman < ConflictError; end
+  class ConcurrentTransition < ConflictError; end
+  class InvalidTransition < UnprocessableEntityError; end
+  class ActorTypeRequired < BadRequestError; end
+  class InvalidField < BadRequestError; end
+  class EmptyPatch < BadRequestError; end
+  class MalformedJSON < BadRequestError; end
+  class SessionNotFound < NotFoundError; end
+  class DesktopBindFailed < ServiceUnavailableError; end
+  class HandoffNotFound < NotFoundError; end
+  class HandoffUnavailable < ConflictError; end
+  class HandoffNotHuman < NotFoundError; end
+  class HandoffExpired < GoneError; end
+  class HandoffPersistenceFailed < ServerError; end
+
+  # Problem `type` → its typed error; anything else falls back to the status tier.
+  PROBLEM_TYPE_CLASSES = {
+    "/errors/control-not-held" => ControlNotHeld,
+    "/errors/lease-expired" => LeaseExpired,
+    "/errors/lease-refresh-unavailable" => LeaseRefreshUnavailable,
+    "/errors/another-session-human" => AnotherSessionHuman,
+    "/errors/concurrent-transition" => ConcurrentTransition,
+    "/errors/invalid-transition" => InvalidTransition,
+    "/errors/actor-type-required" => ActorTypeRequired,
+    "/errors/invalid-field" => InvalidField,
+    "/errors/empty-patch" => EmptyPatch,
+    "/errors/malformed-json" => MalformedJSON,
+    "/errors/session-not-found" => SessionNotFound,
+    "/errors/desktop-bind-failed" => DesktopBindFailed,
+    "/errors/handoff-not-found" => HandoffNotFound,
+    "/errors/handoff-unavailable" => HandoffUnavailable,
+    "/errors/handoff-not-human" => HandoffNotHuman,
+    "/errors/handoff-expired" => HandoffExpired,
+    "/errors/handoff-persistence-failed" => HandoffPersistenceFailed,
+    "/errors/precondition-failed" => PreconditionFailedError,
+    "/errors/precondition-required" => PreconditionRequiredError,
+    "/errors/unauthorized" => UnauthorizedError,
+    "/errors/forbidden" => ForbiddenError
+  }.freeze
+
+  def self.problem_class_for(problem_type) = PROBLEM_TYPE_CLASSES[problem_type]
+
+  # Failures with no HTTP response, or a timeout status (408/504) without a
+  # problem body. #retry_after is the response's Retry-After in seconds, when
+  # a timeout status set one.
+  class TimeoutError < Error
+    attr_accessor :retry_after
+  end
+  class ConnectionError < Error; end
+  class ReadyTimeoutError < Error; end
+
+  # The runtime reported failed, terminated or unavailable before the
+  # lifecycle operation finished.
+  class RuntimeFailedError < Error
+    attr_reader :runtime_id, :state
+
+    def initialize(message = nil, runtime_id: nil, state: nil)
+      @runtime_id = runtime_id
+      @state = state
+      super(message || "Computer runtime #{runtime_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
+
+  # An event stream could not be re-established: it reconnected
+  # RetryPolicy::STREAM_RECONNECT_BUDGET times in a row without delivering an
+  # event. #cause is the last failure, when there was one. Reopen it with the
+  # last event id you processed. A ConnectionError, so connection rescues
+  # keep catching it.
+  class StreamLostError < ConnectionError
+    attr_reader :op, :request_id
+
+    def initialize(op: nil, request_id: nil, cause: nil)
+      @op = op
+      @request_id = request_id
+      @stream_cause = cause
+      detail = cause ? ": #{cause.message}" : ""
+      super(PineSandbox.with_context("event stream lost (reconnect budget exhausted)#{detail}", op: op, request_id: request_id))
+    end
+
+    def cause = @stream_cause || super
+  end
+
+
+  # The source binding is retained; no sandbox deletion follows this error.
+  class StopSaveError < Error
+    attr_reader :save_error
+
+    def initialize(error, retryable: nil)
+      @save_error = error
+      @retryable = retryable
+      super("Computer stop could not confirm saved state: #{error.message}")
+    end
+
+    def problem_type = save_error.respond_to?(:problem_type) ? save_error.problem_type : "/errors/stop-failed"
+    def retryable? = @retryable.nil? ? (save_error.respond_to?(:retryable?) && save_error.retryable?) : @retryable
+  end
+
+  # BindError and its subclasses are the typed outcomes of Computer#attach.
+  # `#status` is the HTTP status when one is available; `#cause` is the
+  # underlying ApiError, so callers can inspect the raw response if needed.
+  class BindError < Error
+    attr_reader :status, :cause
+
+    def initialize(message, status: nil, cause: nil)
+      @status = status
+      @cause = cause
+      super(message)
+    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
+
+    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")
+    end
+  end
+
+  # ControlTokenError is the typed outcome of exchanging a `pk_` client key at
+  # the portal's POST /v1/control-token (ControlTokenSource).
+  # `#status`/`#body`/`#request_id` carry the portal response for diagnosis;
+  # `#op` is "<METHOD> <path>" (WHICH portal call — the primary spine); `#retry_after`
+  # is the parsed Retry-After (seconds) on a RateLimited.
+  class ControlTokenError < Error
+    attr_reader :status, :body, :request_id, :op, :retry_after
+
+    def initialize(message, status: nil, body: nil, request_id: nil, op: nil, retry_after: nil)
+      @status = status
+      @body = body
+      @request_id = request_id
+      @op = op
+      @retry_after = retry_after
+      super(PineSandbox.with_context(message, op: op, request_id: request_id))
+    end
+  end
+
+  # 401 — the pk_ key is missing, malformed, or unknown, raised by the
+  # control-token mint. (The attach-credentials flow reports its own 401 as an
+  # AttachCredentialsError with #status == 401, so a `rescue AttachCredentialsError`
+  # around attach stays complete.)
+  class InvalidClientKey < ControlTokenError; end
+
+  # 403 — the key is valid but its scope may not mint control-plane tokens
+  # (needs pk_session or pk_admin).
+  class InsufficientScope < ControlTokenError; end
+
+  # 429 — the portal rate-limited the mint. `#retry_after` is honored on retry.
+  class RateLimited < ControlTokenError; end
+
+  # Base error for the pk_-authenticated Portal machine API. #op is
+  # "<METHOD> <path>" and #request_id is the secondary precision handle.
+  class PortalError < Error
+    attr_reader :status, :body, :request_id, :op, :problem_type, :reason, :retry_after
+
+    def initialize(message, status: nil, body: nil, request_id: nil, op: nil,
+                   problem_type: nil, reason: nil, retry_after: nil)
+      @status = status
+      @body = body
+      @request_id = request_id
+      @op = op
+      @problem_type = problem_type
+      @reason = reason
+      @retry_after = retry_after
+      super(PineSandbox.with_context(message, op: op, request_id: request_id))
+    end
+  end
+
+  # AttachCredentialsError + subclasses are the typed outcomes of optional
+  # pre-registration and per-attach credential minting.
+  class AttachCredentialsError < PortalError; end
+
+  # A failed project-authenticated read of the available location catalog.
+  class LocationDiscoveryError < PortalError; end
+
+  # 404 — the computer_id is deleted or owned by another project. A genuinely
+  # new id is lazily recorded during first attach.
+  class UnknownComputerError < AttachCredentialsError; end
+
+  # 409/422 — registration refused: the computer_id is taken by another
+  # project, tombstoned, or malformed.
+  class ComputerRegistrationError < AttachCredentialsError; end
+
+  # 422 — deletion refused: the computer_id is malformed (not a lowercase
+  # UUIDv7). Also raised when a custom attach credentials provider cannot
+  # delete. Unknown, deleted, and cross-project ids are not errors (204).
+  class ComputerDeletionError < AttachCredentialsError; end
+
+  # 403 — the key/project/computer is validly identified but may not mint attach
+  # credentials now (scope, project disabled, key revoked, or computer disabled).
+  class ProjectAccessDenied < AttachCredentialsError; end
+
+  # 412 — another attach advanced the authorization revision. Terminal:
+  # reload/adopt the winning integrator database binding; do not allocate a runtime.
+  class BindingRevisionConflictError < AttachCredentialsError
+    attr_reader :current_binding_revision, :current_runtime_id
+
+    def initialize(message, current_binding_revision: nil, current_runtime_id: nil, current_sandbox_id: nil, **kwargs)
+      @current_binding_revision = current_binding_revision
+      @current_runtime_id = current_runtime_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
+  # 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
+
+    def initialize(message, binding_revision:, runtime_id: nil, sandbox_id: nil, credentials: nil, **kwargs)
+      @binding_revision = binding_revision
+      @runtime_id = runtime_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
+  # doesn't support. Fail fast — the SDK pins a major.
+  class SpecVersionMismatch < Error
+    attr_reader :supported, :served
+
+    def initialize(message, supported: nil, served: nil)
+      @supported = supported
+      @served = served
+      super(message)
+    end
+  end
+
+  # The Computer rejected the portal-issued bind_token: bad signature, unknown
+  # kid, iss/aud mismatch, expired, replayed jti, or issued for another runtime.
+  # 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).
+  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
+  deprecate_constant :PodPoisonedError
+
+  # Saved state was unreachable during the bind; the runtime has been
+  # cleaned up. 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.
+  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).
+  # 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
+
+    # The rejection of `api_error` (a 401 answer to a Computer token), with
+    # its operation and request id folded into the message.
+    def self.for_api_error(api_error)
+      new(PineSandbox.with_context(MESSAGE, op: api_error.op, request_id: api_error.request_id),
+          status: 401, cause: api_error)
+    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
+  # Computer. Inherit the legacy 404 tier so existing NotFoundError rescues
+  # remain valid; the original typed ApiError is retained as Exception#cause.
+  class RuntimeGoneError < NotFoundError
+    def initialize(api_error)
+      detail = api_error.error_message.to_s
+      message = "the attached runtime is gone"
+      message = "#{message}: #{detail}" unless detail.empty?
+      super(
+        status: api_error.status,
+        error_code: api_error.error_code,
+        error_message: message,
+        response_body: api_error.response_body,
+        problem_type: api_error.problem_type,
+        problem_extensions: api_error.problem_extensions.dup
+      )
+      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
+  # SDK — capacity frees only when another of the project's Computers stops.
+  # An ApiError, so existing generic rescues keep catching it.
+  class CapacityExceededError < ApiError
+    CODE = "COMPUTER_CAPACITY_EXCEEDED".freeze
+  end
+
+  # 429 COMPUTER_CREATE_RATE_LIMITED on create: the project has started as many
+  # new Computers in the last minute as it may, so nothing was provisioned.
+  # #retry_after is the server's Retry-After in seconds (nil when absent). Not
+  # retried by the SDK; the caller decides when to create again. An ApiError,
+  # so existing generic rescues keep catching it.
+  class CreateRateLimitedError < ApiError
+    CODE = "COMPUTER_CREATE_RATE_LIMITED".freeze
+  end
+end

data/lib/pinesandbox/exec_stream_parser.rb

@@ -0,0 +1,90 @@
+require "json"
+require_relative "sse_frame_parser"
+
+module PineSandbox
+  # Decodes a command's output stream (Session#exec) into Event structs. The
+  # stream is framed by the shared SseFrameParser: each frame's `data:` is
+  # one JSON event whose `type` names it. A frame without data, or whose data
+  # is not a JSON object, is skipped; a block cut off at the end of the stream
+  # is discarded.
+  class ExecStreamParser
+    Event = Struct.new(
+      :type,
+      :id,
+      :data,
+      :text,
+      :execution_count,
+      :execution_time,
+      :timestamp,
+      :results,
+      :error,
+      :raw,
+      keyword_init: true
+    )
+
+    SUPPORTED_EVENT_TYPES = %i[
+      init
+      stdout
+      stderr
+      execution_complete
+      error
+      result
+      ping
+    ].freeze
+
+    def initialize(&block)
+      @frames = SseFrameParser.new
+      @callback = block
+    end
+
+    def parse(chunk, &block)
+      callback = block || @callback
+      raise ArgumentError, "a block is required to receive exec events" unless callback
+
+      @frames.feed(chunk) { |frame| dispatch(frame, callback) }
+    end
+
+    # The end of the stream: a trailing block without its blank line is dropped.
+    def finish(&_block)
+      @frames.finish
+    end
+
+    private
+
+    def dispatch(frame, callback)
+      return if frame.data.empty?
+
+      parsed = begin
+        JSON.parse(frame.data)
+      rescue JSON::ParserError
+        nil
+      end
+      return unless parsed.is_a?(Hash)
+
+      callback.call(
+        Event.new(
+          type: extract_type(parsed, frame.event == "message" ? nil : frame.event),
+          id: frame.id,
+          data: parsed,
+          text: parsed["text"],
+          execution_count: extract_value(parsed, "execution_count", "executionCount"),
+          execution_time: extract_value(parsed, "execution_time", "executionTime"),
+          timestamp: parsed["timestamp"],
+          results: parsed["results"],
+          error: parsed["error"],
+          raw: frame.data
+        )
+      )
+    end
+
+    def extract_type(parsed, fallback)
+      normalized = (parsed["type"] || fallback).to_s.tr("-", "_")
+      normalized.empty? ? nil : normalized.downcase.to_sym
+    end
+
+    def extract_value(parsed, *keys)
+      keys.each { |key| return parsed[key] if parsed.key?(key) }
+      nil
+    end
+  end
+end

data/lib/pinesandbox/models/artifact.rb

@@ -0,0 +1,51 @@
+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
+    # endpoint. Returned by {PineSandbox::Session#list_artifacts} and
+    # {PineSandbox::Session#upload_artifact}. Mirrors the spec `Artifact` schema.
+    Artifact = Struct.new(
+      :id,
+      :session_id,
+      :turn_id,
+      :root,
+      :relative_path,
+      :filename,
+      :content_type,
+      :size,
+      :sha256,
+      :created_by,
+      :created_at,
+      :retention,
+      keyword_init: true
+    ) do
+      def self.from_payload(payload)
+        # filename is the human name WITH extension (basename of the id-prefixed
+        # relative_path) — display/download by this, not `id`. Derive it if an
+        # older Computer omits it.
+        relative_path = payload["relative_path"]
+        new(
+          id: payload["id"],
+          session_id: payload["session_id"],
+          turn_id: payload["turn_id"],
+          root: payload["root"],
+          relative_path: relative_path,
+          filename: payload["filename"] || (relative_path && !relative_path.empty? ? File.basename(relative_path) : nil),
+          content_type: payload["content_type"],
+          size: payload["size"],
+          sha256: payload["sha256"],
+          created_by: payload["created_by"],
+          created_at: payload["created_at"] && Time.parse(payload["created_at"]),
+          retention: payload["retention"]
+        )
+      end
+
+      # True for an agent-produced (task output) artifact.
+      def agent?
+        created_by == "agent"
+      end
+    end
+  end
+end