runtype 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88d76ad46808e8a8a0c06eb80f6b2ff0c61065f12d9762884af36689151f7e37
-  data.tar.gz: ac201871d379ec67b60e7cb6d34b1df429c4723a26b2a5843225ed8d6bbe9ea5
+  metadata.gz: 14f06d191353192fea8029429fafaaf84fdc1237a0798fca43b2eee1125d1f09
+  data.tar.gz: 7b3565f5f24b5c5c427bf373b11e084fd8ae4eb3c39caae4ea34e7840174022e
 SHA512:
-  metadata.gz: 74823bde1a17d632a6a7cb59499e3233452401c157c736f5a5408bd45b37977d2962637841ce2cfa6cffcc8d4b1cc56568235d2db860c780130c9f8a9c9842b3
-  data.tar.gz: 02d0a9123404ebea9d4350e4ed019a96f37db67f9d741b63d7c4d53da6ffc92cc2b89c3247f700aa9a735985fd15a31d98a72e2bd1f37dfcf2e6d3ce36d4fbc7
+  metadata.gz: 4ccf025ce694d254683aebd5d7838abb44f41fceabdf4835c1fdd404fbed4110d37489dd6ffb0fbc4c2ceb19ab8f4535e6dec8340f55ad685c3326aa6f1c30f8
+  data.tar.gz: e9922363afc2c3e43208db368948fd30b71d1145bad41626a043c8a90100ba8b803db0f68e38102b39d0088fa9fe678e9f578320089866f490f185ae9d875563

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to the Runtype Ruby SDK are documented here.
 
+## 0.2.0
+
+- Agents as code: `Runtype.define_agent` builds a validated, immutable
+  `Runtype::AgentDefinition` (snake_case or wire camelCase top-level fields, nested
+  config passed through untouched, account-scoped `tool_…`/`agent_…`/`flow_…` refs
+  rejected). `Runtype::Client#ensure_agent` converges it via `POST /v1/agents/ensure`
+  with the hash-first probe, per-client memo of the server hash, `dry_run:`,
+  `expect_no_changes:` (raises `Runtype::DriftError`), `on_conflict:`, `release:` and
+  `expected_remote_hash:`; `#pull_agent` reads the platform's definition back.
+- `Runtype::AgentDefinition.content_hash_for` computes the platform's canonical
+  content hash: object keys ordered as `JSON.stringify` emits them and numbers
+  rendered as JavaScript renders them, so the hash matches byte for byte (asserted
+  against the shared parity corpus). `ensure_agent` also accepts the wire-shaped
+  definition `pull_agent` returns.
+- `Runtype::Client#run_with_local_tools`: the local-tool pause/resume loop. Executes
+  every paused tool in a batch concurrently and answers them in one resume keyed by
+  the server's per-call id, in JSON or streaming mode, and returns a pause this
+  process does not own (approval, elicitation, detached) untouched. `Runtype::LocalTool` pairs a handler with its schema; `scope: :turn`
+  ships those schemas as `clientTools[]`.
+- Curated errors: `Runtype::ConflictError` (409), `Runtype::EnsureConflictError`,
+  `Runtype::DriftError`, `Runtype::LocalToolError`.
+- The README's dispatch examples now show the wire shape, `agent: { agentId: }` with
+  real `agent_…` ids (the previous `agent: { id: "agt_…" }` examples never referenced
+  a saved agent), and the missing-target error names it.
+
 ## 0.1.0
 
 Initial release.

data/README.md

@@ -25,7 +25,7 @@ client = Runtype::Client.new(api_key: ENV["RUNTYPE_API_KEY"])
 
 # Stream an agent turn
 client.dispatch_stream(
-  agent: { id: "agt_abc123" },
+  agent: { agentId: "agent_abc123" },
   messages: [{ role: "user", content: "Summarize last quarter" }]
 ) do |event|
   print event["delta"] if event.type == "text_delta"
@@ -33,16 +33,71 @@ end
 
 # Or wait for the finished result
 result = client.dispatch(
-  agent: { id: "agt_abc123" },
+  agent: { agentId: "agent_abc123" },
   messages: [{ role: "user", content: "Summarize last quarter" }]
 )
 puts result["executionId"]
 
 # Every documented endpoint is a resource group on the client
 flows = client.flows.list_flows
-agent = client.agents.get_agent_details(id: "agt_abc123")
+agent = client.agents.get_agent_details(id: "agent_abc123")
 ```
 
+The dispatch `agent:` object is an agent definition. Reference a saved agent with
+`agentId:`, or run an inline one with `name:`, `model:`, `systemPrompt:` and the rest
+of the runtime config — nothing is persisted for inline agents.
+
+## Agents as code
+
+Keep the agent's definition in your repo and converge it onto the platform at boot or
+deploy time. `Runtype.define_agent` is pure and local; `ensure_agent` is idempotent
+and non-executing: it probes with a content hash, ships the full definition only when
+the platform reports a miss, appends an immutable version on every change, and never
+deletes. Identity is the agent's name within the API key's account scope.
+
+```ruby
+assistant = Runtype.define_agent(
+  name: "Pricing Assistant",
+  model: "claude-sonnet-4-6",
+  system_prompt: render_prompt(pricing_data),
+  loop_config: { maxTurns: 1 },
+  tools: {
+    toolIds: ["builtin:web_search", "tool:Price List"],   # portable refs only
+    runtimeTools: [
+      { name: "save_quote", toolType: "local", description: "Save a quote",
+        parametersSchema: { type: "object", properties: { total: { type: "number" } } } }
+    ]
+  }
+)
+
+result = client.ensure_agent(assistant, on_conflict: "overwrite", release: "publish")
+result["result"]    # "unchanged" | "created" | "updated"
+result["agentId"]   # dispatch with agent: { agentId: result["agentId"] }
+
+# CI drift gate: raises Runtype::DriftError unless the platform already matches
+client.ensure_agent(assistant, expect_no_changes: true)
+
+# Absorb a dashboard edit back into the repo
+pulled = client.pull_agent("Pricing Assistant")
+pulled["definition"]   # the canonical wire definition; ensure_agent accepts it as-is
+pulled["lastModifiedSource"]
+```
+
+Top-level fields take snake_case or the wire's camelCase; nested config (`tools`,
+`loop_config`, ...) is passed through in wire shape untouched, because its keys can be
+tool names. Definitions must be environment-portable: raw `tool_…`, `agent_…` and
+`flow_…` ids are rejected in favour of `builtin:`, `platform:`, `mcp:` and
+`tool:<name>` / `agent:<name>` / `flow:<name>` references, so the same definition
+converges staging and production.
+
+`ensure_agent` raises `Runtype::EnsureConflictError` (a 409) when the agent's last
+write came from the dashboard, the API or MCP (`#code == "external_modification"`;
+pass `on_conflict: "overwrite"` to converge over it) or when an
+`expected_remote_hash:` no longer matches (`#code == "remote_changed"`).
+`Runtype::AgentDefinition.content_hash_for(definition)` computes the same SHA-256 the
+platform does, over the canonical normalized form (keys ordered as `JSON.stringify`
+emits them, numbers rendered as JavaScript renders them).
+
 ## Authentication
 
 Pass `api_key:`, or leave it out and the client reads `RUNTYPE_API_KEY`. The base URL
@@ -67,7 +122,7 @@ events. Passing a block iterates it and closes the socket for you; the closed st
 comes back so the reconnect handle is still readable.
 
 ```ruby
-stream = client.dispatch_stream(agent: { id: "agt_abc123" }, messages: messages) do |event|
+stream = client.dispatch_stream(agent: { agentId: "agent_abc123" }, messages: messages) do |event|
   case event.type
   when "text_delta"      then print event["delta"]
   when "tool_start"      then puts "calling #{event["toolName"]}"
@@ -109,7 +164,7 @@ from where you left off.
 ```ruby
 detached = false
 
-stream = client.dispatch_stream(agent: { id: "agt_abc123" }, messages: messages) do |event|
+stream = client.dispatch_stream(agent: { agentId: "agent_abc123" }, messages: messages) do |event|
   detached ||= event.detached?
   handle(event)
 end
@@ -130,6 +185,33 @@ client.resume_stream(
 
 `resume` is the non-streaming equivalent. Neither counts against execution limits.
 
+`run_with_local_tools` runs that loop for you. Give it a map of tool name to handler;
+every time the execution pauses on one of them it executes the handler and resumes
+with the output, running all of a turn's parallel calls concurrently and answering
+them in one resume, until the execution ends or pauses on something this process does
+not own (an approval or an elicitation, say), which is returned as-is. Without a block it returns the final JSON body; with a block
+it streams every event of every leg and returns the last leg's stream.
+
+```ruby
+save_goals = Runtype::LocalTool.new(
+  description: "Save the patient's stated goals",
+  parameters_schema: { type: "object", properties: { goals: { type: "array", items: { type: "string" } } } }
+) { |args| Goals.save(args["goals"]); { ok: true } }
+
+result = client.run_with_local_tools(
+  { "save_goals" => save_goals, "lookup_order" => ->(args) { Orders.find(args["id"]) } },
+  agent: { agentId: "agent_abc123" },
+  messages: [{ role: "user", content: "I want to sleep better" }]
+)
+result["status"]   # "completed", or "paused" on a pause you do not own
+```
+
+A bare callable is enough when the saved agent already declares the tool as a
+`toolType: "local"` runtime tool. Pass `scope: :turn` to also ship every
+`Runtype::LocalTool`'s schema as `clientTools[]` for that one dispatch, for tools
+the saved agent does not declare. A missing handler, a handler that raises, or a
+loop that exceeds `max_rounds:` raises `Runtype::LocalToolError`.
+
 ## Errors
 
 Everything the client raises descends from `Runtype::Error`.
@@ -139,18 +221,22 @@ Everything the client raises descends from `Runtype::Error`.
 | `Runtype::AuthenticationError`      | 401, or no API key at construction |
 | `Runtype::PermissionDeniedError`    | 403                                |
 | `Runtype::NotFoundError`            | 404                                |
+| `Runtype::ConflictError`            | 409                                |
+| `Runtype::EnsureConflictError`      | 409 from `ensure_agent`, exposes `#code` |
 | `Runtype::UnprocessableEntityError` | 422                                |
 | `Runtype::RateLimitError`           | 429, exposes `#retry_after`        |
 | `Runtype::APIStatusError`           | any other non-2xx                  |
 | `Runtype::APITimeoutError`          | the request timed out              |
 | `Runtype::APIConnectionError`       | the request never reached the API  |
+| `Runtype::DriftError`               | `ensure_agent(..., expect_no_changes: true)` found drift, exposes `#plan` |
+| `Runtype::LocalToolError`           | `run_with_local_tools` could not run a tool, exposes `#tool_name` and `#cause` |
 
 Status errors carry `#status_code`, `#body` (parsed when the response was JSON), and
 `#headers`.
 
 ```ruby
 begin
-  client.dispatch(agent: { id: "agt_abc123" }, messages: messages)
+  client.dispatch(agent: { agentId: "agent_abc123" }, messages: messages)
 rescue Runtype::RateLimitError => e
   sleep(e.retry_after || 5)
   retry

data/generated/lib/runtype/model_configs/types/post_v1model_configs_request_settings_custom_model.rb

@@ -16,6 +16,8 @@ module Runtype
 
         field :output_cost_per1k_tokens, -> { Integer }, optional: false, nullable: false, api_name: "outputCostPer1kTokens"
 
+        field :reasoning, -> { Runtype::ModelConfigs::Types::PostV1ModelConfigsRequestSettingsCustomModelReasoning }, optional: true, nullable: false
+
         field :supported_response_formats, -> { Internal::Types::Array[String] }, optional: true, nullable: false, api_name: "supportedResponseFormats"
 
         field :supports_streaming, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "supportsStreaming"

data/generated/lib/runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_reasoning.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Runtype
+  module ModelConfigs
+    module Types
+      class PostV1ModelConfigsRequestSettingsCustomModelReasoning < Internal::Types::Model
+        field :default_effort, -> { String }, optional: true, nullable: false, api_name: "defaultEffort"
+
+        field :supported, -> { Internal::Types::Boolean }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/generated/lib/runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model.rb

@@ -16,6 +16,8 @@ module Runtype
 
         field :output_cost_per1k_tokens, -> { Integer }, optional: false, nullable: false, api_name: "outputCostPer1kTokens"
 
+        field :reasoning, -> { Runtype::ModelConfigs::Types::PutV1ModelConfigsIDRequestSettingsCustomModelReasoning }, optional: true, nullable: false
+
         field :supported_response_formats, -> { Internal::Types::Array[String] }, optional: true, nullable: false, api_name: "supportedResponseFormats"
 
         field :supports_streaming, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "supportsStreaming"

data/generated/lib/runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_reasoning.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Runtype
+  module ModelConfigs
+    module Types
+      class PutV1ModelConfigsIDRequestSettingsCustomModelReasoning < Internal::Types::Model
+        field :default_effort, -> { String }, optional: true, nullable: false, api_name: "defaultEffort"
+
+        field :supported, -> { Internal::Types::Boolean }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request_models_item.rb

@@ -14,6 +14,8 @@ module Runtype
 
         field :output_cost_per1k_tokens, -> { Integer }, optional: true, nullable: false, api_name: "outputCostPer1kTokens"
 
+        field :reasoning, -> { Runtype::ProviderKeys::Types::PostV1ProviderKeysIDSyncModelsRequestModelsItemReasoning }, optional: true, nullable: false
+
         field :supported_response_formats, -> { Internal::Types::Array[String] }, optional: true, nullable: false, api_name: "supportedResponseFormats"
 
         field :supports_streaming, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "supportsStreaming"

data/generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request_models_item_reasoning.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Runtype
+  module ProviderKeys
+    module Types
+      class PostV1ProviderKeysIDSyncModelsRequestModelsItemReasoning < Internal::Types::Model
+        field :default_effort, -> { String }, optional: true, nullable: false, api_name: "defaultEffort"
+
+        field :supported, -> { Internal::Types::Boolean }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/generated/lib/runtype.rb

@@ -1126,6 +1126,7 @@ require_relative "runtype/model_configs/types/get_v1model_configs_response"
 require_relative "runtype/model_configs/types/post_v1model_configs_request_provider"
 require_relative "runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_executor_config"
 require_relative "runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_executor_provider"
+require_relative "runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_reasoning"
 require_relative "runtype/model_configs/types/post_v1model_configs_request_settings_custom_model"
 require_relative "runtype/model_configs/types/post_v1model_configs_request_settings"
 require_relative "runtype/model_configs/types/post_v1model_configs_response_configuration_status"
@@ -1161,6 +1162,7 @@ require_relative "runtype/model_configs/types/get_v1model_configs_usage_response
 require_relative "runtype/model_configs/types/get_v1model_configs_usage_response"
 require_relative "runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_executor_config"
 require_relative "runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_executor_provider"
+require_relative "runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_reasoning"
 require_relative "runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model"
 require_relative "runtype/model_configs/types/put_v1model_configs_id_request_settings"
 require_relative "runtype/model_configs/types/put_v1model_configs_id_response_configuration_status"
@@ -1473,6 +1475,7 @@ require_relative "runtype/provider_keys/types/patch_v1provider_keys_id_response_
 require_relative "runtype/provider_keys/types/patch_v1provider_keys_id_response"
 require_relative "runtype/provider_keys/types/post_v1provider_keys_id_discover_models_response_models_item"
 require_relative "runtype/provider_keys/types/post_v1provider_keys_id_discover_models_response"
+require_relative "runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request_models_item_reasoning"
 require_relative "runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request_models_item"
 require_relative "runtype/provider_keys/types/post_v1provider_keys_id_sync_models_response"
 require_relative "runtype/provider_status/types/get_v1provider_status_response_embedding_models_value"

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
+    ].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