pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/adapters/snapshot_adapter.rb

@@ -0,0 +1,37 @@
+module PineSandbox
+  module Adapters
+    # Reads the Computer's most recently saved browser state through
+    # `GET /state`, with the Computer token (`ct_`). Returned by
+    # {Computer#snapshot}.
+    #
+    # `latest` returns the raw response body (a JSON Hash): the saved state
+    # as an encrypted envelope. Callers that just forward the bytes to
+    # external storage can store it as-is; callers that want to decrypt
+    # locally can inspect `body["envelope_version"]`. To save the current
+    # state first, call {Computer#checkpoint}.
+    class SnapshotAdapter
+      # @param coordinator [CoordinatorAdapter] the HTTP client wired to
+      #   this Computer.
+      # @param token_provider [Proc] returning the `ct_*` computer token.
+      #   Lazy so the token is fetched only on first use (the read can
+      #   come well after sandbox-create when the user actually asks for
+      #   state).
+      def initialize(coordinator:, token_provider:)
+        @coordinator = coordinator
+        @token_provider = token_provider
+      end
+
+      # Returns the most recently saved state as a JSON Hash, or nil when
+      # nothing has been saved yet (a fresh Computer before its first
+      # checkpoint).
+      #
+      # Raises:
+      #   PineSandbox::ServiceUnavailableError — state persistence is not
+      #     available on this Computer.
+      #   PineSandbox::UnauthorizedError — ct_ token rejected.
+      def latest
+        @coordinator.get_latest_snapshot(token: @token_provider.call)
+      end
+    end
+  end
+end

data/lib/pinesandbox/agent_events.rb

@@ -0,0 +1,213 @@
+require "time"
+
+module PineSandbox
+  # Immutable typed view of a public agent event's `controller_changed` frame. Unknown
+  # trigger strings are preserved so additive server changes remain
+  # forward-compatible.
+  AgentControlChange = Data.define(
+    :controller,
+    :mode_epoch,
+    :computer_epoch,
+    :trigger,
+    :changed_at
+  )
+
+  # The agent's caller-facing narration (a `progress` frame).
+  AgentProgress = Data.define(:text)
+
+  # Caller-authored input the coordinator accepted (an `input` frame): the run
+  # goal, an answer, or steering. context is run-only. An answer's input
+  # opens the turn it belongs to.
+  AgentInput = Data.define(:kind, :text, :context)
+
+  # One step of the agent's work (an `activity` frame). Upsert by id: every
+  # step ends with exactly one outcome ("completed", "failed", "declined", or
+  # "interrupted" when its turn stopped first), after "running" when the step
+  # takes time, and parallel steps interleave. A reader resuming mid-stream may
+  # see an outcome without its start. "completed" means the step finished, not
+  # that the goal succeeded. kind says what the step was for a person
+  # ("browser", "command", "file", "skill", "tool"); the set grows, so treat a
+  # kind you don't know as a generic step. title is the Computer's own
+  # description of the step in the imperative ("Open Home Page – E-Label",
+  # "Click “Log in”", "Edit notes.md", "Use skill book-flight"); state says how
+  # it went. Display it as is and do not parse it. facts are what the step
+  # acted on (an ActivityFacts), or nil.
+  AgentActivity = Data.define(:id, :state, :kind, :title, :facts) do
+    def initialize(id:, state:, kind: nil, title: nil, facts: nil) = super
+  end
+
+  # What a step acted on, from the Computer's own record of the work: never a
+  # command line, tool argument or anything typed into a page. Every member is
+  # optional. steps lists the actions a browser step ran, in order; a failed
+  # action is the last one.
+  ActivityFacts = Data.define(:page, :target, :files, :skill, :steps) do
+    def initialize(page: nil, target: nil, files: [], skill: nil, steps: []) = super
+  end
+
+  # The page a browser step ended on: its title and address (scheme, host, path).
+  ActivityPage = Data.define(:title, :url)
+  # An element a browser step acted on: its accessibility role and visible name.
+  ActivityTarget = Data.define(:role, :name)
+  # A work-directory file a step touched, and how ("created", "edited",
+  # "deleted", "moved" or "read").
+  ActivityFile = Data.define(:path, :change)
+  # One of your learned skills a step used.
+  ActivitySkill = Data.define(:name)
+
+  # A picture of the Computer's screen (a `frame` frame), taken after a step
+  # that may have changed it. media_type is "image/webp" today; skip a type you
+  # can't show. data is the decoded image (a binary String).
+  AgentFrame = Data.define(:media_type, :width, :height, :data, :observed_at, :activity) do
+    def initialize(media_type:, width:, height:, data:, observed_at: nil, activity: nil) = super
+  end
+
+  # Typed public activity envelope yielded by AgentMode#events. It subclasses Hash so
+  # existing callers using event["type"], #dig, or JSON serialization remain
+  # compatible while new callers use named accessors and typed payload helpers.
+  class AgentEvent < Hash
+    CONTROLLERS = %w[agent human locked].freeze
+
+    class << self
+      # Wrap a parsed public activity Hash without changing its string-keyed wire
+      # representation. Already-wrapped events are returned as-is.
+      def wrap(value)
+        return value if value.is_a?(self)
+        raise ArgumentError, "agent event must be a Hash" unless value.is_a?(Hash)
+
+        new.update(value)
+      end
+    end
+
+    def schema_version = self["schema_version"]
+    def event_id = self["event_id"]
+    def task_id = self["task_id"]
+    def session = self["session"]
+    def computer_id = self["computer_id"]
+    # The turn this event belongs to; the same ID run, answer and turn reads
+    # return. Absent on older records without a trustworthy turn.
+    def turn_id = self["turn_id"]
+    def type = self["type"]
+    def controller = self["controller"]
+    def mode_epoch = self["mode_epoch"]
+    def payload = self["payload"]
+
+    def timestamp
+      parse_time(self["ts"])
+    end
+
+    # Return the authoritative typed control transition for a
+    # `controller_changed` frame, or nil for another/malformed event. The
+    # controller + mode_epoch pair lives on the envelope; commit metadata lives
+    # in payload. Requiring the complete shape prevents a partial frame from
+    # being mistaken for an authoritative transition.
+    def control_change
+      return nil unless type == "controller_changed"
+      return nil unless CONTROLLERS.include?(controller)
+      return nil unless nonnegative_integer?(mode_epoch)
+      return nil unless payload.is_a?(Hash)
+
+      computer_epoch = payload["computer_epoch"]
+      trigger = payload["trigger"]
+      changed_at = parse_time(payload["changed_at"])
+      return nil unless nonnegative_integer?(computer_epoch)
+      return nil unless trigger.is_a?(String) && changed_at
+
+      AgentControlChange.new(
+        controller: controller,
+        mode_epoch: mode_epoch,
+        computer_epoch: computer_epoch,
+        trigger: trigger,
+        changed_at: changed_at
+      )
+    end
+
+    # The narration of a `progress` frame, or nil for another/malformed event.
+    def progress
+      return nil unless type == "progress" && payload.is_a?(Hash)
+
+      text = payload["text"]
+      text.is_a?(String) && !text.empty? ? AgentProgress.new(text: text) : nil
+    end
+
+    # The accepted caller input of an `input` frame, or nil.
+    def input
+      return nil unless type == "input" && payload.is_a?(Hash)
+      return nil unless payload["kind"].is_a?(String) && payload["text"].is_a?(String)
+
+      AgentInput.new(kind: payload["kind"], text: payload["text"], context: string_or_nil(payload["context"]))
+    end
+
+    # The step of an `activity` frame, or nil. A malformed optional title is
+    # dropped; it never costs the step.
+    def activity
+      return nil unless type == "activity" && payload.is_a?(Hash)
+
+      id, state = payload.values_at("activity_id", "state")
+      return nil unless [id, state].all? { |value| value.is_a?(String) && !value.empty? }
+
+      AgentActivity.new(id: id, state: state, kind: string_or_nil(payload["kind"]),
+                        title: string_or_nil(payload["title"]), facts: activity_facts(payload["facts"]))
+    end
+
+    # The picture of a `frame` frame, or nil for another/malformed event.
+    def frame
+      return nil unless type == "frame" && payload.is_a?(Hash)
+
+      media_type, width, height, data = payload.values_at("media_type", "width", "height", "data")
+      return nil unless string_or_nil(media_type) && string_or_nil(data)
+      return nil unless [width, height].all? { |n| n.is_a?(Integer) && n.positive? }
+
+      context = AgentEvent.wrap("type" => "activity", "payload" => payload["activity"]).activity
+      AgentFrame.new(media_type: media_type, width: width, height: height, data: data.unpack1("m0"),
+                     observed_at: parse_time(payload["observed_at"]), activity: context)
+    rescue ArgumentError
+      nil
+    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.
+    def result
+      return nil unless type == "result" && payload.is_a?(Hash)
+
+      payload
+    end
+
+    private
+
+    # Each fact member is read on its own, so a malformed or future member
+    # costs only itself.
+    def activity_facts(value)
+      return nil unless value.is_a?(Hash)
+
+      page, target, skill = value.values_at("page", "target", "skill").map { |m| m.is_a?(Hash) ? m : nil }
+      page = page && ActivityPage.new(title: string_or_nil(page["title"]), url: string_or_nil(page["url"]))
+      target = target && ActivityTarget.new(role: string_or_nil(target["role"]), name: string_or_nil(target["name"]))
+      skill = skill && string_or_nil(skill["name"]) && ActivitySkill.new(name: skill["name"])
+      files = Array(value["files"]).filter_map do |file|
+        next unless file.is_a?(Hash) && string_or_nil(file["path"])
+
+        ActivityFile.new(path: file["path"], change: string_or_nil(file["change"]))
+      end
+      steps = Array(value["steps"]).filter_map { |step| string_or_nil(step) }
+      return nil if page.nil? && target.nil? && skill.nil? && files.empty? && steps.empty?
+
+      ActivityFacts.new(page: page, target: target, files: files, skill: skill, steps: steps)
+    end
+
+    def string_or_nil(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
+    def nonnegative_integer?(value)
+      value.is_a?(Integer) && value >= 0
+    end
+
+    def parse_time(value)
+      return nil unless value.is_a?(String)
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/pinesandbox/agent_mode.rb

@@ -0,0 +1,252 @@
+require "securerandom"
+require_relative "agent_events"
+require_relative "agent_turn"
+
+module PineSandbox
+  # session.agent.* — hand Pine's agent the loop. Work is addressed by turn: a
+  # turn starts when a run or an answer is accepted and ends when the agent
+  # finishes, fails, is canceled or asks a question. Every ending is the turn's
+  # result, with its usage, and an answer is the next turn. Save the turn_id
+  # #run and #answer return and #wait for that turn; nothing else needs to be
+  # kept between calls or processes. The agent's memory persists across runs
+  # on a session. Mutations (run/steer/answer/cancel/reset) use the Computer
+  # token (ct_); reads (wait/status/turns/events) use the session token (ps_),
+  # or the Computer token for a session handle read without one.
+  #
+  # Reached via {Session#agent}: `session.agent.run("book a table")`.
+  class AgentMode
+    # One turn read holds at most this long, inside its HTTP read timeout;
+    # #wait repeats reads.
+    WAIT_HOLD_SECONDS = 25
+    WAITING_STATES = %w[running canceling].freeze
+    # A run with its key, an answer and a cancel name the same turn when sent
+    # again, so a lost response is resent: a network fault, a request timeout,
+    # or a gateway status that cannot say whether the Computer acted. Waits
+    # grow from 1 to 5 seconds, never shorter than Retry-After, and stop once
+    # the next send would start past the budget, measured from the first send
+    # (the transport's own retries inside each send count too), which
+    # outlasts a coordinator restart. Steer is never resent.
+    RESEND_BUDGET_SECONDS = 30
+    LOST_RESPONSE_STATUSES = [408, 502, 503, 504].freeze
+
+    def initialize(session)
+      @session = session
+    end
+
+    # run(goal) — start a turn. Returns the AgentTurn; save its turn_id, then
+    # #wait for it. Raises on 409 when a turn is already running (session-busy)
+    # or a person holds control. Starting new work leaves an unanswered question
+    # unanswered for good.
+    #
+    # idempotency_key: names this submission, for example your saved message
+    # ID. A run with the same key returns the turn that key admitted instead of
+    # starting another. Without one, #run uses a key of its own so its resend
+    # after a lost response is safe; a process that restarts must pass the key
+    # it saved to get the same turn back. When no response arrives within the
+    # resend budget, #run raises the last failure — a ConnectionError,
+    # TimeoutError or ApiError — extended with RunUnconfirmedError, with
+    # #idempotency_key naming the key to send it again with.
+    #
+    # secrets: optional name→value secrets, delivered to the session secrets
+    # file ($SESSION_SECRETS) once the run is admitted and before the agent
+    # starts — never model-visible text; the agent references values as $NAME.
+    # See the spec's SessionSecrets schema for the naming rules and lifecycle
+    # (ephemeral; re-send after re-attach).
+    def run(goal, context: nil, skills: nil, constraints: nil, secrets: nil, idempotency_key: nil)
+      idempotency_key ||= SecureRandom.uuid_v7
+      send_turn do
+        coordinator.agent_run(token: ct, name: name, goal: goal,
+                              context: context, skills: skills, constraints: constraints,
+                              secrets: secrets, idempotency_key: idempotency_key)
+      end
+    rescue TimeoutError, ConnectionError, ApiError => e
+      if lost_response?(e)
+        e.idempotency_key = idempotency_key
+        e.extend(RunUnconfirmedError)
+      end
+      raise
+    end
+
+    # wait(turn_id:, timeout:) — the AgentTurn once it ends: with a question
+    # ("needs_input"; read #question), already answered ("answered"; continue
+    # with #next_turn_id), or finished ("completed", "failed" or "canceled";
+    # read #result). After timeout seconds it returns the turn as it is, still
+    # "running" or "canceling"; timeout 0 reads it once. Waiting never cancels
+    # the turn or follows its next turn. A read whose response was lost (a
+    # network fault, a 408, or a gateway 502, 503 or 504), or whose problem is
+    # marked retryable, is read again until the timeout; any other error
+    # raises, including a missing or expired turn. A read that comes back
+    # sooner than it asked the Computer to hold is followed by a pause of up
+    # to a second, so waiting never spins.
+    def wait(turn_id:, timeout:)
+      deadline = monotonic + timeout
+      failures = 0
+      loop do
+        hold = (deadline - monotonic).clamp(0, WAIT_HOLD_SECONDS).floor
+        started = monotonic
+        begin
+          turn = coordinator.agent_turn(token: read_token, name: name, turn_id: turn_id, wait_seconds: hold)
+        rescue TimeoutError, ConnectionError, ApiError => e
+          retryable = lost_response?(e) || (e.is_a?(ApiError) && e.retryable? == true)
+          raise unless retryable && monotonic < deadline
+
+          failures += 1
+          sleep([retry_delay(failures, e), deadline - monotonic].min)
+          next
+        end
+        failures = 0
+        return AgentTurn.wrap(turn) unless WAITING_STATES.include?(turn["state"]) && monotonic < deadline
+
+        # The Computer holds whole seconds, and may answer before the hold
+        # (or ignore it): pause up to a second before reading again.
+        sleep([1, deadline - monotonic].min) if hold.zero? || monotonic - started < hold
+      end
+    end
+
+    # answer(turn_id:, answer:) — answer the question that ended turn_id.
+    # Returns the AgentTurn the answer opened, which continues the same goal;
+    # save its turn_id and #wait for it. Only the session's latest turn can be
+    # answered. Sending the same answer again returns the same turn without
+    # delivering anything again, so a lost response is resent; a different
+    # answer to an answered turn raises a 409 (/errors/stale-turn). secrets:
+    # delivered once, before the answer's turn is admitted (a failed delivery
+    # leaves the question open), so the answer can reference a password or
+    # code as $NAME.
+    def answer(turn_id:, answer:, secrets: nil)
+      send_turn { coordinator.agent_answer(token: ct, name: name, turn_id: turn_id, answer: answer, secrets: secrets) }
+    end
+
+    # steer(turn_id:, text:) — add guidance to turn_id while it runs. Returns
+    # the turn. A turn that is not running raises a 409 (/errors/no-active-turn);
+    # at a completion boundary that does not prove the text was not delivered,
+    # so do not replay it automatically. secrets: delivered only once the
+    # steer passes every check.
+    def steer(turn_id:, text:, secrets: nil)
+      AgentTurn.wrap(coordinator.agent_steer(token: ct, name: name, turn_id: turn_id, text: text, secrets: secrets))
+    end
+
+    # cancel(turn_id:) — cancel turn_id while it runs. Returns the AgentTurn,
+    # "canceling" until the agent stops. A turn whose question waits is closed:
+    # it ends "canceled" and can no longer be answered. A turn that has ended
+    # otherwise is returned unchanged, so a lost response is resent. An
+    # answered turn raises a 409 (/errors/stale-turn): cancel the turn its
+    # answer opened instead.
+    def cancel(turn_id:)
+      send_turn { coordinator.agent_cancel(token: ct, name: name, turn_id: turn_id) }
+    end
+
+    # reset — forget the agent's thread so the next run starts on a fresh memory
+    # (the recovery / switch-goal tool). Idle-only (409 while a turn is in
+    # flight); the browser, files, and history are kept.
+    def reset(expected_task_id:)
+      AgentTask.wrap(coordinator.agent_reset(token: ct, name: name, expected_task_id: expected_task_id))
+    end
+
+    # status — the session's AgentTask, which scopes event cursors, and its
+    # latest #turn. Use it to discover work, not to choose a turn to answer,
+    # steer or cancel: those take the turn_id you saved.
+    def status(expected_task_id: nil)
+      AgentTask.wrap(coordinator.agent_task(token: read_token, name: name, **{ expected_task_id: expected_task_id }.compact))
+    end
+
+    # turns — the retained turns as AgentTurns, oldest first, with the same
+    # turn IDs as events and controls.
+    def turns(expected_task_id: nil)
+      coordinator.agent_turns(token: read_token, name: name, expected_task_id: expected_task_id)
+                 .fetch("turns").map { |turn| AgentTurn.wrap(turn) }
+    end
+
+    # events — stream the session's public activity feed; yields AgentEvent, a
+    # typed Hash-compatible envelope. The feed is continuous across turns: a
+    # dropped connection reopens from the last event seen, waiting 0.5 s and
+    # doubling up to 5 s, and after five reconnects in a row that delivered
+    # nothing it raises StreamLostError. Stop reading by breaking out of the
+    # block. Pass last_event_id: to resume from a cursor you saved (with the
+    # Task's expected_task_id:). Without a block, returns an Enumerator that
+    # opens the stream only when iterated (e.g. `session.agent.events.each {
+    # ... }`). Pass frames: false to leave out `frame` events (pictures of the
+    # screen) when you show only the steps.
+    def events(last_event_id: nil, frames: true, expected_task_id: nil, &block)
+      return enum_for(:events, last_event_id: last_event_id, frames: frames, expected_task_id: expected_task_id) unless block
+
+      coordinator.follow_agent_events(token: read_token, name: name, last_event_id: last_event_id, frames: frames, **{ expected_task_id: expected_task_id }.compact) do |event|
+        block.call(AgentEvent.wrap(event))
+      end
+    end
+
+    # Cursor-addressed history. Keep expected_task_id with a persisted cursor.
+    def events_page(after: nil, limit: nil, expected_task_id: nil, frames: true)
+      page = coordinator.agent_events_page(token: read_token, name: name, after: after, limit: limit,
+                                           expected_task_id: expected_task_id, frames: frames)
+      page.merge("events" => page.fetch("events").map { |event| AgentEvent.wrap(event) })
+    end
+
+    private
+
+    # Send a mutation whose repeat names the same turn, resending it after a
+    # lost response, and wrap the turn it returns.
+    def send_turn
+      attempt = 0
+      started = monotonic
+      begin
+        AgentTurn.wrap(yield)
+      rescue TimeoutError, ConnectionError, ApiError => e
+        raise unless lost_response?(e)
+
+        attempt += 1
+        wait = retry_delay(attempt, e)
+        raise if monotonic - started + wait > RESEND_BUDGET_SECONDS
+
+        sleep(wait)
+        retry
+      end
+    end
+
+    # The wait before retry attempt after error: growing from 1 to 5 seconds,
+    # never shorter than the response's Retry-After (an ApiError's, or a
+    # timeout status's).
+    def retry_delay(attempt, error)
+      retry_after = error.respond_to?(:retry_after) ? error.retry_after.to_i : 0
+      [[2**(attempt - 1), 5].min, retry_after].max
+    end
+
+    def lost_response?(error)
+      case error
+      when TimeoutError, ConnectionError then true
+      when ApiError then LOST_RESPONSE_STATUSES.include?(error.status)
+      else false
+      end
+    end
+
+    def name
+      @session.name
+    end
+
+    def coordinator
+      @session.send(:coordinator)
+    end
+
+    def ct
+      @session.parent.computer_token
+    end
+
+    # The session token, or the Computer token for a handle without one.
+    def read_token
+      @session.send(:read_token)
+    end
+
+    def monotonic
+      clock.monotonic
+    end
+
+    # Every resend and wait goes through the data-plane client's clock.
+    def sleep(seconds)
+      clock.sleep(seconds)
+    end
+
+    def clock
+      adapter = coordinator
+      adapter.respond_to?(:clock) ? adapter.clock : PineSandbox::SYSTEM_CLOCK
+    end
+  end
+end

data/lib/pinesandbox/agent_turn.rb

@@ -0,0 +1,75 @@
+require "time"
+
+module PineSandbox
+  # 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
+  # question. Every ending is the turn's "result", with that turn's usage; a
+  # question is a "needs_input" result whose summary is the question, and the
+  # answer starts the next turn. "running" and "canceling" change and
+  # "needs_input" becomes "answered"; every other state is final.
+  #
+  # It subclasses Hash so the wire object stays available as is (turn["state"],
+  # #dig, JSON); the readers below name its fields.
+  class AgentTurn < Hash
+    # Wrap a parsed turn Hash without changing its string-keyed wire
+    # representation. Already-wrapped turns are returned as is.
+    def self.wrap(value)
+      return value if value.is_a?(self)
+      raise ArgumentError, "agent turn must be a Hash" unless value.is_a?(Hash)
+
+      new.update(value)
+    end
+
+    def turn_id = self["turn_id"]
+    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"]
+    def first_event_id = self["first_event_id"]
+    def last_event_id = self["last_event_id"]
+
+    # The question that ended the turn (its result's summary), or nil when the
+    # turn did not end with one.
+    def question
+      ended = result
+      ended.is_a?(Hash) && ended["terminal_reason"] == "needs_input" ? ended["summary"] : nil
+    end
+
+    def started_at = parse_time(self["started_at"])
+    # nil while the turn is running or canceling.
+    def ended_at = parse_time(self["ended_at"])
+
+    private
+
+    def parse_time(value)
+      return nil unless value.is_a?(String)
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # The session's agent Task and its latest turn (spec PublicTask), returned by
+  # AgentMode#status and #reset. The Task scopes event cursors; answer, steer
+  # and cancel the turn you saved, not whichever turn is latest. A Hash, like
+  # AgentTurn.
+  class AgentTask < Hash
+    def self.wrap(value)
+      return value if value.is_a?(self)
+      raise ArgumentError, "agent task must be a Hash" unless value.is_a?(Hash)
+
+      task = new.update(value)
+      task["turn"] = AgentTurn.wrap(value["turn"]) if value["turn"].is_a?(Hash)
+      task
+    end
+
+    def task_id = self["task_id"]
+    def session = self["session"]
+    def computer_id = self["computer_id"]
+    # The latest turn, an AgentTurn; nil before the first run.
+    def turn = self["turn"]
+  end
+end