runtype 0.3.0 → 0.11.1

data/lib/runtype/content_hash.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Runtype
+  # Canonical content hashes for the config-as-code ensure surfaces other than
+  # agents (see {AgentDefinition.content_hash_for}). Each is a wire contract
+  # with the API and the TypeScript SDK, pinned by the corpora under
+  # `packages/shared/test-fixtures/*-content-hash/cases.json`. A key absent
+  # from a Hash plays JavaScript's `undefined` (dropped); `nil` plays `null`.
+  module ContentHash
+    MAX_ARRAY_INDEX = 4_294_967_294
+    FPO_OPTIONAL_SECTIONS = %w[records schedules secrets evals skills].freeze
+    SERVER_SET_STACK_FIELDS = %w[detected declared hiddenAt].freeze
+
+    module_function
+
+    # @param steps [Array<Hash>] a flow's steps.
+    # @return [String] SHA-256 hex over the canonical step list.
+    def flow(steps)
+      sha256(normalize_flow_steps(steps))
+    end
+
+    # @param steps [Array<Hash>]
+    # @return [Array<Hash>] the canonical steps, sorted by `order`.
+    def normalize_flow_steps(steps)
+      Array(steps).each_with_index
+                  .map { |step, index| legacy_flow_step_identity(stringify(step), index) }
+                  .each_with_index
+                  .sort_by { |step, index| [step_order(step), index] }
+                  .map { |step, _index| normalize_flow_step(step) }
+    end
+
+    # @param definition [Hash] `{ name:, manifest: { frontmatter:, runtype:, body: } }`.
+    # @return [String] SHA-256 hex; the frontmatter name is identity, not content.
+    def skill(definition)
+      manifest = plain(stringify(definition)["manifest"])
+      frontmatter = plain(manifest["frontmatter"]).except("name")
+      runtype_block = manifest["runtype"]
+      body = manifest["body"]
+      sha256(
+        "frontmatter" => normalize_value(frontmatter),
+        "runtype" => runtype_block.is_a?(Hash) ? normalize_value(runtype_block) : {},
+        "body" => body.is_a?(String) ? body : ""
+      )
+    end
+
+    # @param definition [Hash] `{ name:, description:, toolType:, parametersSchema:, config: }`.
+    # @return [String] SHA-256 hex; the name is identity, not content.
+    def tool(definition)
+      wire = stringify(definition)
+      normalized = {}
+      normalized["toolType"] = wire["toolType"] if wire.key?("toolType")
+      normalized["description"] = wire["description"] if truthy?(wire["description"])
+      normalized["parametersSchema"] = object_or_empty(wire["parametersSchema"])
+      normalized["config"] = object_or_empty(wire["config"])
+      sha256(normalized)
+    end
+
+    # @param definition [Hash] `{ name:, type:, behavior:?, inbound:?, outbound:?, status:? }`.
+    # @return [String] SHA-256 hex.
+    def surface(definition)
+      wire = stringify(definition)
+      type_entry = wire.key?("type") ? { "type" => wire["type"] } : {}
+      behavior = wire["behavior"]
+      normalized = type_entry.dup
+      normalized["behavior"] = behavior.is_a?(Hash) ? normalize_value(type_entry.merge(behavior)) : type_entry.dup
+      normalized["status"] = truthy?(wire["status"]) ? wire["status"] : "draft"
+      normalized["environment"] = "development"
+      sha256(normalized)
+    end
+
+    # @param definition [Hash] `{ name:, description:?, icon:?, spec:? }`.
+    # @return [String] SHA-256 hex; the name is identity, not content.
+    def product(definition)
+      wire = stringify(definition)
+      normalized = {}
+      normalized["description"] = wire["description"] if truthy?(wire["description"])
+      normalized["icon"] = wire["icon"] if truthy?(wire["icon"])
+      normalized["spec"] = object_or_empty(as_saved_stack(wire["spec"]))
+      sha256(normalized)
+    end
+
+    # @param fpo [Hash] a Full Product Object.
+    # @return [String] SHA-256 hex; `_meta` and `product.name` are excluded.
+    def fpo(fpo)
+      wire = stringify(fpo)
+      normalized = {}
+      normalized["version"] = normalize_value(wire["version"]) unless wire["version"].nil?
+      normalized["product"] = normalize_value(plain(wire["product"]).except("name"))
+      %w[capabilities tools surfaces].each { |section| normalized[section] = normalize_value(wire[section] || []) }
+      FPO_OPTIONAL_SECTIONS.each do |section|
+        normalized[section] = normalize_value(wire[section]) unless wire[section].nil?
+      end
+      sha256(normalized)
+    end
+
+    # @param definition [Hash] an eval suite `{ name:, target:, cases:, virtual:, ... }`.
+    # @return [String] SHA-256 hex; cases sort by name, grader order is kept.
+    def eval_suite(definition)
+      wire = stringify(definition)
+      mode = truthy?(wire["recordedToolMode"]) ? wire["recordedToolMode"] : "next_step"
+      policy = truthy?(wire["recordedToolUnmatchedPolicy"]) ? wire["recordedToolUnmatchedPolicy"] : "fail"
+      canonical = {}
+      canonical["target"] = sort_keeping_nil(wire["target"]) if wire.key?("target")
+      canonical["virtual"] = wire["virtual"] if wire.key?("virtual")
+      canonical["recordedToolMode"] = mode unless mode == "next_step"
+      canonical["recordedToolUnmatchedPolicy"] = policy unless policy == "fail"
+      cases = Array(wire["cases"]).map { |entry| plain(entry) }
+      canonical["cases"] = cases.each_with_index
+                                .sort_by { |entry, index| [utf16(entry["name"].to_s), index] }
+                                .map { |entry, _index| canonical_case(entry) }
+      sha256(canonical)
+    end
+
+    # Drops nil entries and orders object keys the way `JSON.stringify` emits
+    # sorted keys, recursively; arrays keep their order.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def normalize_value(value)
+      case value
+      when Array then value.map { |entry| normalize_value(entry) }
+      when Hash
+        entries = stringify(value)
+        entries.keys.sort_by { |key| json_key_order(key) }.each_with_object({}) do |key, out|
+          out[key] = normalize_value(entries[key]) unless entries[key].nil?
+        end
+      else value
+      end
+    end
+
+    # @return [String]
+    def sha256(value)
+      Digest::SHA256.hexdigest(Runtype::CanonicalJSON.generate(value))
+    end
+
+    def canonical_case(entry)
+      canonical = {}
+      canonical["name"] = entry["name"] if entry.key?("name")
+      canonical["input"] = sort_keeping_nil(entry["input"]) if entry.key?("input")
+      canonical["expected"] = sort_keeping_nil(entry["expected"]) if entry.key?("expected")
+      canonical["expect"] = Array(entry["expect"]).map { |grader| sort_keeping_nil(grader) }
+      canonical
+    end
+
+    def normalize_flow_step(step)
+      normalized = {
+        "type" => step["type"].is_a?(String) ? step["type"] : "",
+        "name" => step["name"].is_a?(String) ? step["name"] : "",
+        "enabled" => step["enabled"] != false
+      }
+      normalized["when"] = step["when"] if step["when"].is_a?(String)
+      normalized["config"] = normalize_flow_config(step["config"])
+      normalized["order"] = step_order(step)
+      normalized
+    end
+
+    # Sorts keys and keeps nil; one level of array items is normalized, deeper
+    # arrays keep their insertion key order, exactly as the TypeScript SDK does.
+    def normalize_flow_config(config)
+      return {} unless config.is_a?(Hash)
+
+      entries = stringify(config)
+      entries.keys.sort_by { |key| json_key_order(key) }.each_with_object({}) do |key, out|
+        value = entries[key]
+        out[key] =
+          case value
+          when Hash then normalize_flow_config(value)
+          when Array then value.map { |item| item.is_a?(Hash) ? normalize_flow_config(item) : js_emission_order(item) }
+          else value
+          end
+      end
+    end
+
+    # The key order `JSON.stringify` gives an object nobody sorted: canonical
+    # array indexes first, then insertion order.
+    def js_emission_order(value)
+      case value
+      when Array then value.map { |entry| js_emission_order(entry) }
+      when Hash
+        entries = stringify(value)
+        indexes, others = entries.keys.partition { |key| json_key_order(key).first.zero? }
+        (indexes.sort_by { |key| json_key_order(key) } + others).to_h { |key| [key, js_emission_order(entries[key])] }
+      else value
+      end
+    end
+
+    def sort_keeping_nil(value)
+      case value
+      when Array then value.map { |entry| sort_keeping_nil(entry) }
+      when Hash
+        entries = stringify(value)
+        entries.keys.sort_by { |key| json_key_order(key) }.to_h { |key| [key, sort_keeping_nil(entries[key])] }
+      else value
+      end
+    end
+
+    # A legacy step missing `name`/`order` defaults to `Step N`/`N`, as flow pull emits.
+    def legacy_flow_step_identity(step, index)
+      step.merge(
+        "name" => step["name"].is_a?(String) ? step["name"] : "Step #{index + 1}",
+        "order" => step["order"].is_a?(Numeric) ? step["order"] : index + 1
+      )
+    end
+
+    def step_order(step)
+      order = step.is_a?(Hash) ? step["order"] : nil
+      order.is_a?(Numeric) ? order : 0
+    end
+
+    def json_key_order(key)
+      if key.match?(/\A(?:0|[1-9]\d*)\z/) && key.to_i <= MAX_ARRAY_INDEX
+        [0, key.to_i, []]
+      else
+        [1, 0, utf16(key)]
+      end
+    end
+
+    def utf16(value)
+      value.encode("UTF-16LE").unpack("v*")
+    end
+
+    def object_or_empty(value)
+      value.is_a?(Hash) ? normalize_value(value) : {}
+    end
+
+    # `spec` with its stack as a save stores it: server-set fields dropped, `hidden` deduplicated.
+    def as_saved_stack(spec)
+      return spec unless spec.is_a?(Hash)
+
+      wire = stringify(spec)
+      return wire unless wire["stack"].is_a?(Hash)
+
+      stack = stringify(wire["stack"]).except(*SERVER_SET_STACK_FIELDS)
+      stack["hidden"] = stack["hidden"].uniq if stack["hidden"].is_a?(Array)
+      wire.merge("stack" => stack)
+    end
+
+    def plain(value)
+      value.is_a?(Hash) ? stringify(value) : {}
+    end
+
+    def stringify(value)
+      value.is_a?(Hash) ? value.to_h { |key, entry| [key.to_s, entry] } : {}
+    end
+
+    # JavaScript truthiness for the values a definition can hold.
+    def truthy?(value)
+      !(value.nil? || value == false || value == "" || (value.is_a?(Numeric) && value.zero?))
+    end
+
+    private_class_method :canonical_case, :normalize_flow_step, :normalize_flow_config, :js_emission_order,
+                         :sort_keeping_nil, :step_order, :json_key_order, :utf16, :object_or_empty, :plain,
+                         :stringify, :truthy?
+  end
+end

data/lib/runtype/detached_follow.rb

@@ -60,6 +60,18 @@ module Runtype
       seqs.max&.to_s
     end
 
+    # The agent-version keys a dispatch or resume body reports. The events
+    # alias never repeats them, so a followed envelope carries them forward.
+    RELEASE_KEYS = %w[agentVersionId alias agentTargetResolution].freeze
+
+    # @param response [Object]
+    # @return [Hash] the release keys `response` carries, or an empty Hash.
+    def release_fields(response)
+      return {} unless response.is_a?(Hash)
+
+      response.slice(*RELEASE_KEYS).compact
+    end
+
     # @param data [Hash]
     # @return [Boolean]
     def detached_await?(data)

data/lib/runtype/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Runtype
   # Base class for every error the overlay raises. Rescue this to catch all of
   # them regardless of which generated resource produced the failure.
@@ -28,12 +30,20 @@ module Runtype
     # Translates a Fern-generated error into the curated equivalent. Errors that
     # are not generated API errors are returned unchanged.
     #
+    # A socket timeout is translated too: the generated methods rescue
+    # `Net::HTTPRequestTimeout`, a 408 response class no socket ever raises, so
+    # `Net::OpenTimeout`, `Net::ReadTimeout` and `Net::WriteTimeout` reach here
+    # untranslated. They all descend from `Timeout::Error`, so one clause covers
+    # connect, read and write, matching {Runtype::Streaming::Connection}.
+    #
     # @param error [Exception]
     # @return [Exception]
     def self.from_generated(error)
       case error
       when Runtype::Errors::TimeoutError
         APITimeoutError.new("Request timed out")
+      when ::Timeout::Error
+        APITimeoutError.new("Request timed out: #{error.message}")
       when Runtype::Errors::ResponseError
         from_response(status: error.code, body: error.message)
       when Runtype::Errors::ApiError
@@ -180,24 +190,58 @@ module Runtype
     end
   end
 
-  # Raised by `ensure_agent(definition, expect_no_changes: true)` when the
-  # platform's definition no longer matches the repo's.
+  # Raised by `ensure_agent(definition, expect_no_changes: true)`, and by the
+  # other `ensure_*` methods, when the platform's definition no longer matches
+  # the repo's.
   class DriftError < Error
     # @return [Hash] the dry-run plan: `"changes"`, `"changedKeys"`,
-    #   `"contentHash"`, `"remoteHash"`, `"agentId"`.
+    #   `"contentHash"`, `"remoteHash"`, and the entity's id.
     attr_reader :plan
 
     # @param plan [Hash]
     # @param name [String, nil]
-    def initialize(plan, name: nil)
+    # @param entity [String] what drifted, e.g. `"Agent"` or `"Flow"`.
+    # @param pull_hint [String] the call that absorbs the remote edit.
+    # @param ensure_hint [String] the method that converges it.
+    def initialize(plan, name: nil, entity: "Agent", pull_hint: "client.pull_agent(name)",
+                   ensure_hint: "ensure_agent")
       @plan = plan
-      changed = Array(plan["changedKeys"]).join(", ")
+      changed = (Array(plan["changedKeys"]) + self.class.skill_changes(plan) + self.class.deployment_changes(plan) +
+                 self.class.publish_changes(plan))
+                .join(", ")
       super(
-        "Agent #{(name || plan["agentId"] || "definition").inspect} drifted: plan is #{plan["changes"].inspect} " \
-        "(changed: #{changed.empty? ? "n/a" : changed}). Run client.pull_agent(name) to absorb the remote edit " \
-        "into your repo, or re-run ensure_agent to converge."
+        "#{entity} #{(name || plan["agentId"] || "definition").inspect} drifted: plan is #{plan["changes"].inspect} " \
+        "(changed: #{changed.empty? ? "n/a" : changed}). Run #{pull_hint} to absorb the remote edit " \
+        "into your repo, or re-run #{ensure_hint} to converge."
       )
     end
+
+    # @param plan [Hash]
+    # @return [Array<String>] `skill:<name> (<action>)` for each binding the plan would change.
+    def self.skill_changes(plan)
+      Array(plan["skillBindings"]).reject { |binding| binding["action"] == "unchanged" }
+                                  .map { |binding| "skill:#{binding["name"]} (#{binding["action"]})" }
+    end
+
+    # @param plan [Hash]
+    # @return [Array<String>] `publish (pending)` when a `release: "publish"` dry run would re-aim the pointer.
+    def self.publish_changes(plan)
+      plan["publishPending"] == true ? ["publish (pending)"] : []
+    end
+
+    # @param plan [Hash]
+    # @return [Array<String>] `deploy:<alias> (pointer)` and `deploy:<alias> (bindings)`
+    #   for an alias move or binding-name change the plan reports.
+    def self.deployment_changes(plan)
+      deployment = plan["deployment"]
+      return [] unless deployment.is_a?(Hash)
+
+      alias_name = deployment["alias"]
+      [
+        ("deploy:#{alias_name} (pointer)" if deployment["changed"] == true),
+        ("deploy:#{alias_name} (bindings)" if deployment["bindingsChanged"] == true)
+      ].compact
+    end
   end
 
   # A local tool could not be run during `run_with_local_tools`: the server
@@ -235,7 +279,9 @@ module Runtype
   class APIConnectionError < Error; end
 
   # Runs a block, re-raising Fern-generated errors as their curated equivalents
-  # so callers keep one stable rescue surface across regenerations.
+  # so callers keep one stable rescue surface across regenerations. A socket
+  # timeout raised inside a generated call is curated here too, as
+  # {Runtype::APITimeoutError}.
   #
   # @example
   #   Runtype.wrap_errors { client.flows.list_flows }
@@ -243,7 +289,7 @@ module Runtype
   # @return [Object] whatever the block returns.
   def self.wrap_errors
     yield
-  rescue Runtype::Errors::ApiError => e
+  rescue Runtype::Errors::ApiError, ::Timeout::Error => e
     raise Runtype::Error.from_generated(e)
   end
 end

data/lib/runtype/local_tool_runner.rb

@@ -60,6 +60,7 @@ module Runtype
     # @return [Hash] the final JSON response body.
     def dispatch_with_local_tools(registry, params, max_rounds, request_options)
       response = dispatch(request_options: request_options, **params)
+      release = Runtype::DetachedFollow.release_fields(response)
       answered = AnsweredCalls.new
       replayed = false
       cursor = nil
@@ -80,6 +81,7 @@ module Runtype
             tool_outputs: registry.execute(batch),
             request_options: request_options
           )
+          release = release.merge(Runtype::DetachedFollow.release_fields(response))
           # A buffered continuation answers the leg in full; only a durable-lane
           # acknowledgement needs the run's events followed instead.
           next unless Runtype::DetachedFollow.detached_ack?(response)
@@ -90,7 +92,7 @@ module Runtype
         followed = Runtype::DetachedFollow.follow_buffered(
           self, collector.batch_execution_id, after: cursor, request_options: request_options
         )
-        response = followed.envelope
+        response = followed.envelope.merge(release)
         cursor = followed.cursor
         replayed = true
       end

data/lib/runtype/raw_client_timeout.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Runtype
+  # Timeout handling for the Fern-generated low-level transport.
+  #
+  # `Runtype::BaseClient` accepts no timeout and builds its
+  # `Runtype::Internal::Http::RawClient` with the generator's 60 second default,
+  # so every generated resource call ignored the timeout {Runtype::Client} was
+  # given. {Runtype::Client} seeds that transport through {apply}, which also
+  # gives it the per-call `request_options[:timeout_in_seconds]` override the
+  # generated methods document.
+  module RawClientTimeout
+    # Sends one request under the caller's `timeout_in_seconds` when it asked
+    # for one, and under the client-wide timeout otherwise. The override runs
+    # on a copy of the transport, so a client shared across threads is never
+    # mutated for the duration of one call.
+    #
+    # @param request [Runtype::Internal::Http::BaseRequest]
+    # @return [Net::HTTPResponse]
+    def send(request)
+      seconds = RawClientTimeout.timeout_in_seconds(request)
+      return super if seconds.nil? || seconds == @timeout
+
+      scoped = dup
+      scoped.instance_variable_set(:@timeout, seconds)
+      # INVARIANT: the copy's own timeout equals the override, so its send takes the branch above and cannot recur.
+      scoped.send(request)
+    end
+
+    # Reads the per-request timeout off a request's options under either key
+    # spelling, matching {Runtype::Client}'s streaming path.
+    #
+    # @param request [Runtype::Internal::Http::BaseRequest]
+    # @return [Float, nil] nil when no override was asked for, or when the
+    #   value is not a number.
+    def self.timeout_in_seconds(request)
+      options = request.respond_to?(:request_options) ? request.request_options : nil
+      return nil unless options.respond_to?(:[])
+
+      value = options[:timeout_in_seconds] || options["timeout_in_seconds"]
+      value.nil? ? nil : Float(value, exception: false)
+    end
+
+    # Seeds a generated transport with the client-wide timeout and gives it
+    # per-request override handling.
+    #
+    # @param raw_client [Runtype::Internal::Http::RawClient]
+    # @param timeout [Numeric] the client-wide timeout, in seconds.
+    # @return [Runtype::Internal::Http::RawClient] the same object.
+    def self.apply(raw_client, timeout:)
+      raw_client.instance_variable_set(:@timeout, Float(timeout))
+      raw_client.extend(self)
+      raw_client
+    end
+  end
+end

data/lib/runtype/sdk_version.rb

@@ -8,7 +8,8 @@ module Runtype
   # generator). The generated barrel does not require that file, so nothing
   # collides today, but re-declaring it here would make the overlay's version
   # depend on generator require order.
-  SDK_VERSION = "0.3.0"
+  # Mirrored from ../../package.json by scripts/sync-sdk-versions.mjs; never hand-edit.
+  SDK_VERSION = "0.11.1"
 
   # Outbound User-Agent identifying the SDK kind, version, and language, e.g.
   # "runtype-sdk/0.1.0 (ruby)". The `runtype-sdk/` prefix is what the API's

data/lib/runtype.rb

@@ -25,6 +25,7 @@ require_relative "../generated/lib/runtype"
 
 require_relative "runtype/sdk_version"
 require_relative "runtype/errors"
+require_relative "runtype/raw_client_timeout"
 require_relative "runtype/streaming/event"
 require_relative "runtype/streaming/line_decoder"
 require_relative "runtype/streaming/event_parser"
@@ -33,6 +34,8 @@ require_relative "runtype/streaming/event_stream"
 require_relative "runtype/canonical_json"
 require_relative "runtype/agent_definition"
 require_relative "runtype/agent_ensure"
+require_relative "runtype/content_hash"
+require_relative "runtype/config_ensure"
 require_relative "runtype/agent_release_aliases"
 require_relative "runtype/local_tools"
 require_relative "runtype/detached_follow"