runtype 0.1.0 → 0.2.1

data/lib/runtype/agent_definition.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Runtype
+  # Builds an {AgentDefinition}: the pure-local, no-I/O half of agent
+  # config-as-code. Converge it onto the platform with
+  # {Runtype::Client#ensure_agent}.
+  #
+  #   assistant = Runtype.define_agent(
+  #     name: "Pricing Assistant",
+  #     model: "claude-sonnet-4-6",
+  #     system_prompt: render_prompt(pricing_data),
+  #     loop_config: { maxTurns: 1 }
+  #   )
+  #
+  # Top-level fields accept snake_case or the wire's camelCase
+  # (`system_prompt:` and `systemPrompt:` are the same field). Nested config
+  # (`loop_config`, `tools`, ...) is passed through in wire shape untouched:
+  # its keys can be tool names such as `"save_patient_goals"`, so they are
+  # never case-converted.
+  #
+  # @param fields [Hash] `name:` plus any of the agent runtime config keys
+  #   ({AgentDefinition::CONFIG_KEYS}), `description:` and `icon:`.
+  # @return [Runtype::AgentDefinition]
+  # @raise [ArgumentError] on a missing name, an unknown field, or an
+  #   account-scoped `tool_…` / `agent_…` / `flow_…` reference.
+  def self.define_agent(**fields)
+    AgentDefinition.new(fields)
+  end
+
+  # A repo-owned agent definition, validated locally and hashed exactly as the
+  # API hashes it (see {#content_hash}). Immutable once built: every String,
+  # Hash and Array it holds is a frozen copy of the caller's input.
+  class AgentDefinition
+    # The agent runtime config surface that `ensure` converges. Keys outside
+    # this list are rejected by {Runtype.define_agent} and, on the wire, are
+    # excluded from the content hash so a stray field cannot produce a hash
+    # the server can never reproduce. Pinned against the generated
+    # `AgentPullResponseDefinitionConfig` model by the test suite.
+    CONFIG_KEYS = %w[
+      model systemPrompt temperature maxTokens topP topK frequencyPenalty
+      presencePenalty seed tools reasoning advisor loopConfig voice
+      errorHandling artifacts loggingPolicy piiRedaction temporal memory
+      sandbox tenancyStrategy durability state contextManagement
+    ].freeze
+
+    TOP_LEVEL_KEYS = (%w[name description icon] + CONFIG_KEYS).freeze
+
+    # snake_case spellings of every multi-word top-level key, derived from
+    # {CONFIG_KEYS} so the two can never disagree.
+    SNAKE_CASE_ALIASES = CONFIG_KEYS.to_h { |key| [key.gsub(/[A-Z]/) { |upper| "_#{upper.downcase}" }, key] }
+                                    .reject { |snake, camel| snake == camel }.freeze
+    private_constant :SNAKE_CASE_ALIASES
+
+    # Largest canonical array index (2**32 - 2). `JSON.stringify` emits such
+    # keys first, in ascending numeric order, ahead of every other key.
+    MAX_ARRAY_INDEX = 4_294_967_294
+    private_constant :MAX_ARRAY_INDEX
+
+    # @return [String] the agent name — its identity within the account scope.
+    attr_reader :name
+
+    # @return [String, nil]
+    attr_reader :description
+
+    # @return [String, nil]
+    attr_reader :icon
+
+    # @return [Hash{String => Object}] the runtime config, wire-shaped, string keys.
+    attr_reader :config
+
+    # @return [String] SHA-256 (hex) over {#normalized}, computed once at
+    #   construction. Sent as the hash-only probe in the ensure protocol; the
+    #   server recomputes and returns its own on every response.
+    attr_reader :content_hash
+
+    # Accepts an existing definition, the flat Hash {Runtype.define_agent}
+    # takes, or a wire-shaped definition with a nested `config` (what
+    # {Runtype::Client#pull_agent} returns), so a pulled definition can be
+    # ensured straight back.
+    #
+    # @param value [Runtype::AgentDefinition, Hash]
+    # @return [Runtype::AgentDefinition]
+    def self.from(value)
+      return value if value.is_a?(AgentDefinition)
+      return new(value) if value.is_a?(Hash)
+
+      raise ArgumentError, "expected a Runtype::AgentDefinition or a Hash, got #{value.class}"
+    end
+
+    # @param fields [Hash] the flat shape (see {Runtype.define_agent}) or the
+    #   wire shape (`{"name", "description"?, "icon"?, "config" => {...}}`).
+    def initialize(fields)
+      raise ArgumentError, "define_agent requires a definition Hash" unless fields.is_a?(Hash)
+
+      normalized = flatten_wire_shape(fields.to_h { |key, value| [canonical_key(key), value] })
+      unknown = normalized.keys - TOP_LEVEL_KEYS
+      unless unknown.empty?
+        raise ArgumentError,
+              "define_agent: unknown field(s): #{unknown.join(", ")}. Allowed fields are name, description, icon, " \
+              "and the agent runtime config surface (#{CONFIG_KEYS.join(", ")})."
+      end
+
+      @name = normalized["name"]
+      unless @name.is_a?(String) && !@name.empty?
+        raise ArgumentError, "define_agent requires a non-empty String \"name\""
+      end
+
+      @name = @name.dup.freeze
+      @description = normalized["description"]&.dup&.freeze
+      @icon = normalized["icon"]&.dup&.freeze
+      @config = CONFIG_KEYS.each_with_object({}) do |key, config|
+        value = normalized[key]
+        config[key] = deep_freeze(deep_stringify_keys(value)) unless value.nil?
+      end.freeze
+
+      non_portable = non_portable_refs(@config)
+      unless non_portable.empty?
+        raise ArgumentError,
+              "define_agent: account-scoped reference(s) at #{non_portable.join(", ")}. Definitions must be " \
+              "environment-portable — tool_…/agent_…/flow_… IDs belong to one account/environment. Use " \
+              "builtin:/platform:/mcp: references, or reference a saved resource by name — tool:<name>, " \
+              "agent:<name>, or flow:<name> instead."
+      end
+
+      @content_hash = self.class.content_hash_for(to_h)
+      freeze
+    end
+
+    # The wire definition sent to `POST /v1/agents/ensure`.
+    #
+    # @return [Hash{String => Object}]
+    def to_h
+      wire = { "name" => name }
+      wire["description"] = description unless description.nil?
+      wire["icon"] = icon unless icon.nil?
+      wire["config"] = config
+      wire
+    end
+
+    # The canonical normalized form the content hash is computed over: keys
+    # ordered as `JSON.stringify` emits them, nil entries dropped, empty
+    # description/icon dropped, config restricted to {CONFIG_KEYS} (unknown
+    # keys excluded). Byte-identical to the TypeScript SDK's
+    # `normalizeAgentDefinition` once serialized.
+    #
+    # @param definition [Hash] a wire-shaped definition
+    #   (`{"name", "description"?, "icon"?, "config"?}`), such as the one
+    #   {Runtype::Client#pull_agent} returns.
+    # @return [Hash{String => Object}]
+    def self.normalize(definition)
+      wire = definition.to_h { |key, value| [key.to_s, value] }
+      description = wire["description"]
+      icon = wire["icon"]
+      raw_config = wire["config"].is_a?(Hash) ? wire["config"].to_h { |key, value| [key.to_s, value] } : {}
+
+      canonical = { "name" => wire["name"] }
+      canonical["description"] = description if description.is_a?(String) && !description.empty?
+      canonical["icon"] = icon if icon.is_a?(String) && !icon.empty?
+      canonical["config"] = CONFIG_KEYS.sort.each_with_object({}) do |key, out|
+        value = raw_config[key]
+        out[key] = normalize_value(value) unless value.nil?
+      end
+      canonical
+    end
+
+    # SHA-256 (hex) over the canonical normalized form of a wire-shaped
+    # definition. Matches the hash the API returns for the same definition.
+    #
+    # @param definition [Hash] see {.normalize}.
+    # @return [String]
+    def self.content_hash_for(definition)
+      Digest::SHA256.hexdigest(Runtype::CanonicalJSON.generate(normalize(definition)))
+    end
+
+    # Drops nil entries and orders object keys the way V8's `JSON.stringify`
+    # emits them — canonical array indexes first in ascending numeric order,
+    # then the remaining keys sorted by UTF-16 code units — recursively; arrays
+    # keep their order. The TypeScript normalizer sorts keys and then
+    # serializes, and serialization applies this order, so hashing the same
+    # bytes requires it here.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def self.normalize_value(value)
+      case value
+      when Array
+        value.map { |entry| normalize_value(entry) }
+      when Hash
+        entries = value.to_h { |key, entry| [key.to_s, entry] }
+        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
+    private_class_method :normalize_value
+
+    # @param key [String]
+    # @return [Array] a sort key: `[0, index]` for canonical array indexes,
+    #   `[1, utf16 code units]` for everything else.
+    def self.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, key.encode("UTF-16LE").unpack("v*")]
+      end
+    end
+    private_class_method :json_key_order
+
+    # @return [Hash{String => Object}] see {.normalize}.
+    def normalized
+      self.class.normalize(to_h)
+    end
+
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(AgentDefinition) && other.name == name && other.description == description &&
+        other.icon == icon && other.config == config
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      content_hash.hash
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} name=#{name.inspect} model=#{config["model"].inspect}>"
+    end
+
+    private
+
+    # @param key [String, Symbol]
+    # @return [String]
+    def canonical_key(key)
+      string = key.to_s
+      SNAKE_CASE_ALIASES.fetch(string, string)
+    end
+
+    # Lifts a wire-shaped `config` Hash into the flat authoring shape, so both
+    # spellings validate through the same path.
+    #
+    # @param fields [Hash{String => Object}]
+    # @return [Hash{String => Object}]
+    def flatten_wire_shape(fields)
+      return fields unless fields["config"].is_a?(Hash)
+
+      config = fields["config"].to_h { |key, value| [canonical_key(key), value] }
+      fields.except("config").merge(config)
+    end
+
+    # @param value [Object]
+    # @return [Object] a fresh copy of the structure with String keys throughout.
+    def deep_stringify_keys(value)
+      case value
+      when Hash then value.to_h { |key, entry| [key.to_s, deep_stringify_keys(entry)] }
+      when Array then value.map { |entry| deep_stringify_keys(entry) }
+      when String then value.dup
+      else value
+      end
+    end
+
+    # Freezes every Hash, Array and String in a structure the constructor just
+    # copied, so the definition that was validated is the one that gets hashed
+    # and sent: no caller can reach through {#config} or {#to_h} and slip an
+    # account-scoped reference past the constructor checks.
+    #
+    # @param value [Object]
+    # @return [Object] the same value, frozen throughout.
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |entry| deep_freeze(entry) }
+      when Array then value.each { |entry| deep_freeze(entry) }
+      end
+      value.freeze
+    end
+
+    # Collects account-scoped references, which the v1 ensure surface rejects
+    # because a definition must converge every environment unchanged.
+    # Mirrors `collectNonPortableToolRefs` in the TypeScript SDK.
+    #
+    # @param config [Hash]
+    # @return [Array<String>] JSON-path-ish locations of the offending refs.
+    def non_portable_refs(config)
+      tools = config["tools"]
+      return [] unless tools.is_a?(Hash)
+
+      found = []
+      scan_array = lambda do |value, path|
+        next unless value.is_a?(Array)
+
+        value.each_with_index { |ref, index| found << "#{path}[#{index}]" if account_scoped?(ref) }
+      end
+      scan_keys = lambda do |value, path|
+        next unless value.is_a?(Hash)
+
+        value.each_key { |key| found << "#{path}.#{key}" if account_scoped?(key) }
+      end
+
+      scan_array.call(tools["toolIds"], "tools.toolIds")
+      scan_keys.call(tools["toolConfigs"], "tools.toolConfigs")
+      scan_keys.call(tools["perToolLimits"], "tools.perToolLimits")
+      scan_array.call(tools.dig("approval", "require"), "tools.approval.require")
+      scan_array.call(tools.dig("subagentConfig", "toolPool"), "tools.subagentConfig.toolPool")
+      scan_array.call(tools.dig("codeModeConfig", "toolPool"), "tools.codeModeConfig.toolPool")
+
+      Array(tools["runtimeTools"]).each_with_index do |runtime_tool, index|
+        next unless runtime_tool.is_a?(Hash) && runtime_tool["config"].is_a?(Hash)
+
+        base = "tools.runtimeTools[#{index}].config"
+        tool_config = runtime_tool["config"]
+        if runtime_tool["toolType"] == "subagent" && tool_config["agentId"].to_s.start_with?("agent_")
+          found << "#{base}.agentId"
+        elsif runtime_tool["toolType"] == "flow" && tool_config["flowId"].to_s.start_with?("flow_")
+          found << "#{base}.flowId"
+        end
+      end
+      found
+    end
+
+    # @param ref [Object]
+    # @return [Boolean]
+    def account_scoped?(ref)
+      ref.is_a?(String) && ref.start_with?("tool_")
+    end
+  end
+end

data/lib/runtype/agent_ensure.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Runtype
+  # Agent config-as-code on {Runtype::Client}: converge a repo-owned
+  # {AgentDefinition} onto the platform (`POST /v1/agents/ensure`) and pull the
+  # platform's definition back (`GET /v1/agents/pull`). Protocol:
+  # `docs/adr/0003-agent-config-as-code-ensure.md`.
+  module AgentEnsure
+    # Idempotently makes the platform's definition of this agent match
+    # `definition`. Identity is the agent name within the API key's account
+    # scope. Hash-first: probes with the local content hash and only ships the
+    # full definition when the server reports a miss. Every change appends an
+    # immutable version; nothing is ever deleted. Non-executing.
+    #
+    # @param definition [Runtype::AgentDefinition, Hash] see {Runtype.define_agent}.
+    # @param dry_run [Boolean] plan without writing (the CI drift gate).
+    # @param expect_no_changes [Boolean] implies `dry_run`; raises
+    #   {Runtype::DriftError} unless the plan is `"none"`.
+    # @param on_conflict [String, Symbol, nil] `"error"` (default: 409 when the
+    #   agent's last write came from the dashboard/API/MCP) or `"overwrite"`.
+    # @param release [String, Symbol, nil] `"publish"` also re-aims the
+    #   published-version pointer; default `"none"`.
+    # @param expected_remote_hash [String, nil] binds a dry run to its apply:
+    #   the write proceeds only if the remote still hashes to this value.
+    # @param request_options [Hash] see {Runtype::Client#dispatch}.
+    # @return [Hash] `{"result" => "unchanged"|"created"|"updated", "agentId",
+    #   "versionId", "contentHash"}`, or for a dry run `{"result" => "plan",
+    #   "changes" => "none"|"create"|"update", "changedKeys", "contentHash", ...}`.
+    #   `contentHash` is always the server-computed canonical hash.
+    # @raise [Runtype::EnsureConflictError] on a 409 (`external_modification`
+    #   or `remote_changed`).
+    # @raise [Runtype::DriftError] with `expect_no_changes:` when the plan is
+    #   not `"none"`.
+    def ensure_agent(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
+                     expected_remote_hash: nil, request_options: {})
+      definition = Runtype::AgentDefinition.from(definition)
+      passthrough = {
+        onConflict: on_conflict&.to_s,
+        release: release&.to_s,
+        expectedRemoteHash: expected_remote_hash
+      }.compact
+
+      if dry_run || expect_no_changes
+        plan = ensure_request(
+          { name: definition.name, definition: definition.to_h, dryRun: true, **passthrough }, request_options
+        )
+        unless plan["result"] == "plan"
+          raise Runtype::Error, "Expected a plan result from dryRun, got #{plan["result"].inspect}"
+        end
+        raise Runtype::DriftError.new(plan, name: definition.name) if expect_no_changes && plan["changes"] != "none"
+
+        return plan
+      end
+
+      local_hash = definition.content_hash
+      memo_key = "#{definition.name}:#{local_hash}"
+      content_hash = ensure_memo[memo_key] || local_hash
+
+      probe = ensure_request({ name: definition.name, contentHash: content_hash, **passthrough }, request_options)
+      return memoize_ensure(memo_key, probe) unless probe["result"] == "definitionRequired"
+
+      converged = ensure_request({ name: definition.name, definition: definition.to_h, **passthrough }, request_options)
+      if converged["result"] == "definitionRequired"
+        raise Runtype::Error, "Server reported definitionRequired for a full-definition request"
+      end
+
+      memoize_ensure(memo_key, converged)
+    end
+
+    # The canonical definition and provenance of an agent by name — the
+    # absorb-drift direction. `contentHash` reflects the live agent state.
+    #
+    # @param name [String]
+    # @param request_options [Hash]
+    # @return [Hash] `{"agentId", "definition" => {...}, "contentHash",
+    #   "lastModifiedSource", "updatedAt", "versionId", "warnings"?}`.
+    # @raise [Runtype::NotFoundError] when no agent by that name is in scope.
+    def pull_agent(name, request_options: {})
+      get_json("v1/agents/pull", { name: name }, request_options)
+    end
+
+    private
+
+    # @return [Hash{String => String}] `name:localHash` => server hash, so a
+    #   hot process pays the probe once per definition.
+    def ensure_memo
+      @ensure_memo ||= {}
+    end
+
+    # @param memo_key [String]
+    # @param result [Hash]
+    # @return [Hash] the result, for chaining.
+    def memoize_ensure(memo_key, result)
+      ensure_memo[memo_key] = result["contentHash"] if result["result"] != "plan" && result["contentHash"]
+      result
+    end
+
+    # @return [Hash] the decoded response body.
+    # @raise [Runtype::EnsureConflictError] for the protocol's two 409 shapes.
+    def ensure_request(body, request_options)
+      post_json("v1/agents/ensure", body, request_options)
+    rescue Runtype::APIStatusError => e
+      raise Runtype::EnsureConflictError.from_status_error(e) if Runtype::EnsureConflictError.protocol_conflict?(e)
+
+      raise
+    end
+  end
+end

data/lib/runtype/canonical_json.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Runtype
+  # Serializes a value exactly as JavaScript's `JSON.stringify` would, so a
+  # SHA-256 over the result matches the hash the TypeScript SDK and the API
+  # compute for the same definition (the content hash is a wire contract; see
+  # `docs/adr/0003-agent-config-as-code-ensure.md`).
+  #
+  # Ruby's `JSON.generate` already agrees with `JSON.stringify` on strings,
+  # booleans, nil, arrays and objects. Numbers are the exception: Ruby prints
+  # `1.0` where JavaScript prints `1`, and switches to exponent notation at
+  # different magnitudes (`1.0e-05` vs `0.00001`). This module renders numbers
+  # with the ECMA-262 `Number::toString` rules over Ruby's shortest round-trip
+  # digits, which are the same digits V8 picks.
+  module CanonicalJSON
+    module_function
+
+    # @param value [Object] a JSON-compatible value (Hash, Array, String,
+    #   Numeric, true, false, nil).
+    # @return [String] the canonical serialization.
+    def generate(value)
+      case value
+      when Hash
+        "{#{value.map { |key, entry| "#{JSON.generate(key.to_s)}:#{generate(entry)}" }.join(",")}}"
+      when Array
+        "[#{value.map { |entry| generate(entry) }.join(",")}]"
+      when Integer
+        value.to_s
+      when Float
+        number_literal(value)
+      when String, true, false, nil
+        JSON.generate(value)
+      else
+        raise ArgumentError, "CanonicalJSON cannot serialize #{value.class}"
+      end
+    end
+
+    # Renders a Float the way `Number.prototype.toString` does.
+    #
+    # @param value [Float]
+    # @return [String]
+    def number_literal(value)
+      raise ArgumentError, "CanonicalJSON cannot serialize #{value}" unless value.finite?
+      return "0" if value.zero?
+
+      sign = value.negative? ? "-" : ""
+      digits, exponent = shortest_digits(value.abs)
+      k = digits.length
+      n = exponent # the decimal point sits after the first n digits
+
+      body =
+        if n.between?(k, 21)
+          digits + ("0" * (n - k))
+        elsif n.between?(1, 21)
+          "#{digits[0, n]}.#{digits[n..]}"
+        elsif n.between?(-5, 0)
+          "0.#{"0" * -n}#{digits}"
+        else
+          mantissa = k == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+          e = n - 1
+          "#{mantissa}e#{e.negative? ? "-" : "+"}#{e.abs}"
+        end
+      sign + body
+    end
+
+    # Splits a positive finite Float into its shortest round-trip decimal
+    # digits (no leading or trailing zeros) and the position of the decimal
+    # point relative to those digits, per ECMA-262's (s, k, n) decomposition.
+    #
+    # @param value [Float] positive, finite, non-zero.
+    # @return [Array(String, Integer)]
+    def shortest_digits(value)
+      mantissa, exponent = value.to_s.split("e")
+      exp = exponent ? Integer(exponent, 10) : 0
+      integer_part, fraction_part = mantissa.split(".")
+      fraction_part ||= ""
+      raw = integer_part + fraction_part
+      point = integer_part.length + exp
+
+      stripped = raw.sub(/\A0+/, "")
+      point -= raw.length - stripped.length
+      stripped = stripped.sub(/0+\z/, "")
+      [stripped, point]
+    end
+    private_class_method :shortest_digits
+  end
+end