runtype 0.3.0 → 0.11.1

data/lib/runtype/agent_ensure.rb

@@ -16,6 +16,10 @@ module Runtype
       "use deploy: { alias: \"live\" } instead of release: \"publish\", " \
       "and omit both to save without activating."
 
+    # The keys a `version:` hash may carry, mirroring the API's strict
+    # `EnsureVersionMetadata` schema (apps/api/src/lib/ensure-version-metadata.ts).
+    VERSION_METADATA_KEYS = %i[label notes].freeze
+
     # 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
@@ -32,9 +36,22 @@ module Runtype
     #   `deploy:`: `"publish"` also re-aims the `live` alias; default `"none"`.
     # @param deploy [Hash, String, Symbol, nil] activates the saved version at a
     #   release alias, e.g. `{ alias: "pr-482" }` or the bare `"live"`. Omit
-    #   both `release:` and `deploy:` to save without activating.
+    #   both `release:` and `deploy:` to save without activating. `bindings:`
+    #   (`{ "API_URL" => "https://staging..." }`) replaces the alias's
+    #   per-alias secret overrides, as in the TypeScript SDK.
     # @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 version [Hash, nil] provenance recorded on the version row this
+    #   converge appends, e.g. `{ label: "a1b2c3d", notes: "CI run 4821" }`.
+    #   Omit to keep the default `"sdk-ensure"` label and the server's notes.
+    # @param skills [Array<Hash>, nil] the complete set of skills bound to the
+    #   agent, in load order, e.g. `[{ name: "refund-policy", version: 3 }]`.
+    #   `version:` pins a skill versionNumber; omit it to follow the published
+    #   version. Bound skills absent here are unbound; `nil` leaves them alone.
+    # @param capabilities [Array<Hash>, nil] the complete set of capabilities in
+    #   display order, e.g. `[{ toolName: "lookup_order", flow: "Order Lookup" }]`.
+    #   Each names exactly one `flow:`, `agent:` or `tool:` source by name.
+    #   Capabilities absent here are removed; `nil` leaves them alone.
     # @param request_options [Hash] see {Runtype::Client#dispatch}.
     # @return [Hash] `{"result" => "unchanged"|"created"|"updated", "agentId",
     #   "versionId", "contentHash"}`, or for a dry run `{"result" => "plan",
@@ -43,10 +60,13 @@ module Runtype
     # @raise [Runtype::EnsureConflictError] on a 409 (`external_modification`
     #   or `remote_changed`).
     # @raise [Runtype::DriftError] with `expect_no_changes:` when the plan is
-    #   not `"none"`.
-    # @raise [ArgumentError] when both `release:` and `deploy:` are given.
+    #   not `"none"`, would change a skill binding or, with `release:` or
+    #   `deploy:`, would move the alias or change its binding names.
+    # @raise [ArgumentError] when both `release:` and `deploy:` are given, or
+    #   when `version:` carries a key other than `label:` and `notes:`.
     def ensure_agent(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
-                     deploy: nil, expected_remote_hash: nil, request_options: {})
+                     deploy: nil, expected_remote_hash: nil, version: nil, skills: nil, capabilities: nil,
+                     request_options: {})
       raise ArgumentError, RELEASE_DEPLOY_CONFLICT_MESSAGE if release && deploy
 
       definition = Runtype::AgentDefinition.from(definition)
@@ -54,7 +74,10 @@ module Runtype
         onConflict: on_conflict&.to_s,
         release: release&.to_s,
         deploy: deploy_intent(deploy),
-        expectedRemoteHash: expected_remote_hash
+        expectedRemoteHash: expected_remote_hash,
+        version: version_metadata(version),
+        skills: skills&.map(&:to_h),
+        capabilities: capabilities&.map(&:to_h)
       }.compact
 
       if dry_run || expect_no_changes
@@ -64,7 +87,7 @@ module Runtype
         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"
+        raise Runtype::DriftError.new(plan, name: definition.name) if expect_no_changes && drifted?(plan, passthrough)
 
         return plan
       end
@@ -98,13 +121,28 @@ module Runtype
 
     private
 
+    # Whether a dry-run plan fails the drift gate: content or skill-binding
+    # changes, or, when the converge asked to activate an alias, a pointer move
+    # or a binding-name change at that alias.
+    #
+    # @param plan [Hash]
+    # @param passthrough [Hash] the options this converge sends.
+    # @return [Boolean]
+    def drifted?(plan, passthrough)
+      return true if plan["changes"] != "none" || Runtype::DriftError.skill_changes(plan).any?
+
+      deploy_requested = passthrough.key?(:deploy) || passthrough[:release] == "publish"
+      deploy_requested && Runtype::DriftError.deployment_changes(plan).any?
+    end
+
     # Normalizes the two accepted spellings of `deploy:` into the wire shape.
-    # A bare String or Symbol names the alias; a Hash may spell its key either
+    # A bare String or Symbol names the alias; a Hash may spell its keys either
     # way. The alias name itself is never resolved client-side.
     #
     # @param deploy [Hash, String, Symbol, nil]
-    # @return [Hash, nil] `{ alias: "<name>" }`, or nil when nothing was asked.
-    # @raise [ArgumentError] when a Hash carries no alias name.
+    # @return [Hash, nil] `{ alias: "<name>", bindings: {...}? }`, or nil when nothing was asked.
+    # @raise [ArgumentError] when a Hash carries no alias name, or a supplied
+    #   `bindings:` (nil included) is not a Hash of String names to String values.
     def deploy_intent(deploy)
       return nil if deploy.nil?
       return { alias: deploy.to_s } unless deploy.is_a?(Hash)
@@ -112,7 +150,56 @@ module Runtype
       name = deploy[:alias] || deploy["alias"]
       raise ArgumentError, "deploy: needs an alias name, e.g. deploy: { alias: \"live\" }." if name.nil?
 
-      { alias: name.to_s }
+      return { alias: name.to_s } unless deploy.key?(:bindings) || deploy.key?("bindings")
+
+      bindings = deploy.key?(:bindings) ? deploy[:bindings] : deploy["bindings"]
+      { alias: name.to_s, bindings: deploy_bindings(bindings) }
+    end
+
+    # Validates `deploy: { bindings: }`, the per-alias `{{secret:NAME}}`
+    # overrides. Names may be Symbols; values must already be Strings so a
+    # stray nil or number fails here rather than binding its `to_s`.
+    #
+    # @param bindings [Hash]
+    # @return [Hash{String => String}]
+    # @raise [ArgumentError] on a non-Hash or a non-String value.
+    def deploy_bindings(bindings)
+      unless bindings.is_a?(Hash)
+        raise ArgumentError,
+              "deploy: bindings: needs a Hash of secret names to values, e.g. { \"API_URL\" => \"https://...\" }."
+      end
+
+      bindings.each_with_object({}) do |(key, value), acc|
+        unless (key.is_a?(String) || key.is_a?(Symbol)) && value.is_a?(String)
+          raise ArgumentError,
+                "deploy: bindings: maps String names to String values; got #{key.inspect} => #{value.class}."
+        end
+
+        acc[key.to_s] = value
+      end
+    end
+
+    # Normalizes `version:` into the wire shape. Keys may be Symbols or Strings;
+    # an unknown key raises here rather than reaching the server's strict 400.
+    # A hash whose values are all nil is treated as omitted, so
+    # `version: { label: ENV["GIT_SHA"] }` outside CI still saves — the same
+    # reading the API gives an empty label, which falls back to `"sdk-ensure"`.
+    #
+    # @param version [Hash, nil]
+    # @return [Hash, nil] `{ label:, notes: }`, or nil when nothing was asked.
+    # @raise [ArgumentError] on a non-Hash or an unrecognized key.
+    def version_metadata(version)
+      return nil if version.nil?
+      raise ArgumentError, "version: needs a Hash, e.g. version: { label: \"a1b2c3d\" }." unless version.is_a?(Hash)
+
+      metadata = version.each_with_object({}) do |(key, value), acc|
+        name = key.to_sym
+        raise ArgumentError, "version: accepts label: and notes:, not #{key.inspect}." unless
+          VERSION_METADATA_KEYS.include?(name)
+
+        acc[name] = value.to_s unless value.nil?
+      end
+      metadata.empty? ? nil : metadata
     end
 
     # @return [Hash{String => String}] `name:localHash` => server hash, so a

data/lib/runtype/agent_release_aliases.rb

@@ -1,11 +1,29 @@
 # frozen_string_literal: true
 
+require "openssl"
+require "socket"
+require "timeout"
+
 module Runtype
   # Release aliases and deployment receipts on {Runtype::Client}. An agent runs
   # an immutable version; a named mutable alias (`live`, `pr-482`) selects which
   # one, and every activation appends a deployment receipt. Protocol:
   # `docs/adr/0025-agent-release-aliases.md`.
   module AgentReleaseAliases
+    # The fields a `promotion:` hash may carry, mirroring the API's strict
+    # `AgentDeploymentPromotion` schema (apps/api/src/routes/agents/alias-routes.ts)
+    # and the generated {Runtype::Types::AgentDeploymentPromotion} model.
+    PROMOTION_FIELDS = %i[source_agent_id source_version_id source_content_hash source_commit].freeze
+
+    # The failures one {#archive_agent_alias_everywhere} row may absorb: the
+    # curated API tree, plus the transport exceptions Net::HTTP raises below
+    # {Runtype.wrap_errors} (the same set {Runtype::Streaming::Connection}
+    # translates). Everything else is an SDK defect rather than a per-agent
+    # outcome and aborts the sweep loudly instead of becoming a failure row.
+    SWEEP_ISOLATED_ERRORS = [
+      Runtype::Error, Timeout::Error, OpenSSL::SSL::SSLError, SocketError, SystemCallError, IOError
+    ].freeze
+
     # The named pointers of one agent: `live` first, then the preview aliases by
     # name. Archived aliases are omitted unless asked for. Omitting `limit:`
     # returns every pointer; supplying it pages through the same order.
@@ -52,13 +70,20 @@ module Runtype
     #   sent as `If-Match`; required when moving an existing `live` pointer.
     # @param idempotency_key [String, nil] replays the same activation safely.
     # @param reason [String, nil] recorded on the receipt.
+    # @param promotion [Hash, Runtype::Types::AgentDeploymentPromotion, nil] the
+    #   source-organization ids and hashes a cross-organization promotion came
+    #   from, e.g. `{ source_version_id: "agv_9", source_commit: sha }`, linked
+    #   on the receipt. Provenance only: it authorizes nothing, and the
+    #   activating credentials alone decide what the activation may do.
     # @param request_options [Hash]
     # @return [Runtype::AgentAliases::Types::PutV1AgentsIDAliasesAliasResponse]
+    # @raise [ArgumentError] when `promotion:` carries an unrecognized key.
     def activate_agent_alias(agent_id, alias_name, version_id:, revision: nil, idempotency_key: nil, reason: nil,
-                             request_options: {})
+                             promotion: nil, request_options: {})
       params = {
         id: agent_id, alias_: alias_name, version_id: version_id,
-        if_match: revision, idempotency_key: idempotency_key, reason: reason
+        if_match: revision, idempotency_key: idempotency_key, reason: reason,
+        promotion: promotion_provenance(promotion)
       }.compact
       Runtype.wrap_errors do
         release_alias_client.activate_a_version_at_a_release_alias(request_options: request_options, **params)
@@ -127,6 +152,59 @@ module Runtype
       end
     end
 
+    # Every agent in the caller's organization carrying a pointer with this
+    # name, each with the revision to quote back as `If-Match`. This is the read
+    # a "pull request closed" cleanup makes before archiving each pointer; the
+    # per-agent list would need every agent id first. Unpaginated, and `live` is
+    # readable here like any other name.
+    #
+    # @param alias_name [String] e.g. `"pr-482"`.
+    # @param include_archived [Boolean]
+    # @param request_options [Hash]
+    # @return [Runtype::AgentAliases::Types::GetV1AgentAliasesResponse]
+    def list_agent_aliases_by_name(alias_name, include_archived: false, request_options: {})
+      params = { alias_: alias_name }
+      params[:include_archived] = "true" if include_archived
+      Runtype.wrap_errors do
+        release_alias_client.list_release_aliases_with_one_name_across_the_organization(
+          request_options: request_options, **params
+        )
+      end
+    end
+
+    # Archives this pointer on every agent in the organization that carries it,
+    # each under the revision just read, so a concurrent deploy answers 412
+    # instead of racing. An API refusal or transport failure on one agent is
+    # reported in `"failed"` and the sweep continues; any other exception is an
+    # SDK defect and propagates, so a broken response contract never reads as a
+    # completed sweep. Only active pointers are listed, so a second run archives
+    # nothing.
+    #
+    # @param alias_name [String]
+    # @param dry_run [Boolean] report what would be archived and archive nothing.
+    # @param request_options [Hash]
+    # @return [Hash] `{"alias", "archived" => [{"agentId", "agentName",
+    #   "revision", "receiptId"}], "failed" => [{"agentId", "agentName",
+    #   "error", "code"?}]}`, or for a dry run `{"alias", "dryRun" => true,
+    #   "wouldArchive" => [<row>]}` carrying the listed rows unchanged.
+    def archive_agent_alias_everywhere(alias_name, dry_run: false, request_options: {})
+      rows = list_agent_aliases_by_name(alias_name, request_options: request_options).data
+      return { "alias" => alias_name, "dryRun" => true, "wouldArchive" => rows } if dry_run
+
+      rows.each_with_object({ "alias" => alias_name, "archived" => [], "failed" => [] }) do |row, sweep|
+        sweep["archived"] << archive_one_everywhere(row, alias_name, request_options)
+      # Wider than Runtype::Error: a DNS, TLS or connection-reset failure is
+      # raised by Net::HTTP and never reaches Runtype.wrap_errors, so rescuing
+      # the curated tree alone would abort the sweep on one bad row and leave the
+      # remaining pointers active — the opposite of what this method promises.
+      rescue *SWEEP_ISOLATED_ERRORS => e
+        sweep["failed"] << {
+          "agentId" => row.agent_id, "agentName" => row.agent_name,
+          "error" => e.message, "code" => alias_failure_code(e)
+        }.compact
+      end
+    end
+
     private
 
     # @return [Runtype::AgentAliases::Client] the generated sub-client these
@@ -134,5 +212,71 @@ module Runtype
     def release_alias_client
       api.agent_aliases
     end
+
+    # One row of an {#archive_agent_alias_everywhere} sweep. The revision and
+    # receipt reported are the archive response's, not the listed row's.
+    #
+    # @param row [Runtype::AgentAliases::Types::GetV1AgentAliasesResponseDataItem]
+    # @param alias_name [String]
+    # @param request_options [Hash]
+    # @return [Hash]
+    def archive_one_everywhere(row, alias_name, request_options)
+      archived = archive_agent_alias(
+        row.agent_id, alias_name, revision: row.revision.to_s, request_options: request_options
+      )
+      {
+        "agentId" => row.agent_id, "agentName" => row.agent_name,
+        "revision" => archived.revision, "receiptId" => archived.receipt_id
+      }
+    end
+
+    # The alias plane's refusal code for a failed sweep row, matching the
+    # TypeScript helper's `code` field. 428 carries no code of its own, so the
+    # one the typed error uses is supplied here.
+    #
+    # @param error [Runtype::Error]
+    # @return [String, nil]
+    def alias_failure_code(error)
+      body = error.respond_to?(:body) ? error.body : nil
+      code = body["code"] if body.is_a?(Hash)
+      return code.to_s if code
+
+      "alias_revision_required" if error.respond_to?(:status_code) && error.status_code == 428
+    end
+
+    # Normalizes `promotion:` into the wire shape. A generated
+    # {Runtype::Types::AgentDeploymentPromotion} passes through; a Hash may spell
+    # its keys either way, and an unknown key raises here rather than reaching
+    # the server's strict 400 — or, worse, being absorbed as an extra field on
+    # the generated request model. An all-nil hash is treated as omitted, the
+    # same reading the API gives an empty promotion object.
+    #
+    # @param promotion [Hash, Runtype::Types::AgentDeploymentPromotion, nil]
+    # @return [Hash, Runtype::Types::AgentDeploymentPromotion, nil]
+    # @raise [ArgumentError] on a non-Hash or an unrecognized key.
+    def promotion_provenance(promotion)
+      return nil if promotion.nil?
+      return promotion if promotion.is_a?(Runtype::Types::AgentDeploymentPromotion)
+
+      unless promotion.is_a?(Hash)
+        raise ArgumentError,
+              "promotion: needs a Hash of source ids, e.g. promotion: { source_version_id: \"agv_9\" }."
+      end
+
+      provenance = promotion.each_with_object({}) do |(key, value), acc|
+        field = promotion_field(key)
+        raise ArgumentError, "promotion: accepts #{PROMOTION_FIELDS.join(", ")}, not #{key.inspect}." unless field
+
+        acc[field] = value.to_s unless value.nil?
+      end
+      provenance.empty? ? nil : provenance
+    end
+
+    # @param key [String, Symbol] either spelling of a promotion field.
+    # @return [Symbol, nil] the snake_case field name, or nil when unrecognized.
+    def promotion_field(key)
+      field = key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      PROMOTION_FIELDS.include?(field) ? field : nil
+    end
   end
 end

data/lib/runtype/client.rb

@@ -26,6 +26,7 @@ module Runtype
   # clients with different keys or base URLs can coexist in one process.
   class Client
     include Runtype::AgentEnsure
+    include Runtype::ConfigEnsure
     include Runtype::AgentReleaseAliases
     include Runtype::LocalToolRunner
 
@@ -53,7 +54,10 @@ module Runtype
 
     # @param api_key [String, nil] defaults to `RUNTYPE_API_KEY`.
     # @param base_url [String] defaults to `RUNTYPE_BASE_URL`, then production.
-    # @param timeout [Numeric, nil] per-operation socket timeout in seconds.
+    # @param timeout [Numeric, nil] per-operation socket timeout in seconds,
+    #   defaulting to {DEFAULT_TIMEOUT}. Governs the dispatch and streaming
+    #   paths and every generated resource call alike; a single call overrides
+    #   it with `request_options: { timeout_in_seconds: n }`.
     # @param max_retries [Integer] retries for generated resource calls. The
     #   dispatch paths never retry: replaying an execution would run it twice.
     # @raise [Runtype::AuthenticationError] when no API key is available.
@@ -79,6 +83,8 @@ module Runtype
         authorization: bearer_token,
         max_retries: max_retries
       )
+      # WORKAROUND(fern ruby generator): BaseClient takes no timeout, so seed the transport it just built.
+      Runtype::RawClientTimeout.apply(generated_raw_client, timeout: @timeout)
     end
 
     # Executes a flow or agent and waits for the complete JSON response.
@@ -193,6 +199,21 @@ module Runtype
 
     private
 
+    # The transport {#api} shares with every resource sub-client it builds.
+    # Read once at construction, before any sub-client has memoized it.
+    #
+    # @return [Runtype::Internal::Http::RawClient]
+    # @raise [Runtype::Error] when the generated core no longer holds one, which
+    #   means the timeout can no longer be applied to generated calls.
+    def generated_raw_client
+      raw = @api.instance_variable_get(:@raw_client)
+      return raw if raw.is_a?(Runtype::Internal::Http::RawClient)
+
+      raise Runtype::Error,
+            "Runtype::BaseClient no longer exposes @raw_client, so Runtype::Client cannot apply its timeout " \
+            "to generated calls. Rewire Runtype::RawClientTimeout against the generated core's new shape."
+    end
+
     # @return [String]
     def bearer_token
       "Bearer #{@api_key}"

data/lib/runtype/config_ensure.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Runtype
+  # Config-as-code on {Runtype::Client} for skills, flows, tools, surfaces,
+  # products and evals: the same hash-first ensure protocol as
+  # {AgentEnsure#ensure_agent}, mirroring the TypeScript SDK's `*-ensure.ts`
+  # modules option for option. Protocol: `docs/adr/0003-agent-config-as-code-ensure.md`.
+  #
+  # Definitions are plain Hashes in wire shape (camelCase keys, Symbol or
+  # String). Every converge probes with the content hash, ships the full
+  # definition only on `definitionRequired`, memoizes the server's hash per
+  # client, raises {Runtype::EnsureConflictError} on the protocol's 409 and
+  # {Runtype::DriftError} under `expect_no_changes:`.
+  module ConfigEnsure
+    Kind = Struct.new(:label, :pull_hint, :ensure_hint, :hasher, :drift, keyword_init: true)
+
+    SKILL = Kind.new(label: "Skill", pull_hint: "client.pull_skill(name)", ensure_hint: "ensure_skill",
+                     hasher: ContentHash.method(:skill), drift: true)
+    FLOW = Kind.new(label: "Flow", pull_hint: "client.pull_flow(name)", ensure_hint: "ensure_flow",
+                    hasher: ->(definition) { ContentHash.flow(definition["steps"] || []) }, drift: true)
+    TOOL = Kind.new(label: "Tool", pull_hint: "client.pull_tool(name)", ensure_hint: "ensure_tool",
+                    hasher: ContentHash.method(:tool), drift: true)
+    SURFACE = Kind.new(label: "Surface", pull_hint: "client.pull_surface(product_id, name)",
+                       ensure_hint: "ensure_surface", hasher: ContentHash.method(:surface), drift: true)
+    PRODUCT = Kind.new(label: "Product", pull_hint: "client.pull_product(name)", ensure_hint: "ensure_product",
+                       hasher: ContentHash.method(:product), drift: true)
+    EVAL = Kind.new(label: "Eval", pull_hint: "client.pull_eval(name)", ensure_hint: "ensure_eval",
+                    hasher: ContentHash.method(:eval_suite), drift: false)
+
+    # Converges `{ name:, manifest: { frontmatter:, runtype:?, body: } }`. Every
+    # change appends an immutable version.
+    #
+    # @param definition [Hash]
+    # @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) or `"overwrite"`.
+    # @param release [String, Symbol, nil] `"publish"` also re-aims the published-version pointer.
+    # @param expected_remote_hash [String, nil] the write proceeds only if the remote still hashes to this.
+    # @param request_options [Hash] see {Runtype::Client#dispatch}.
+    # @return [Hash] `{"result", "skillId", "versionId", "contentHash"}`, or the dry-run plan.
+    # @raise [Runtype::EnsureConflictError] on the protocol's 409.
+    # @raise [Runtype::DriftError] with `expect_no_changes:` when the plan is not `"none"`.
+    def ensure_skill(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
+                     expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, release: release&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(SKILL, "v1/skills/ensure", wire, skill_wire(wire), options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"skillId", "definition", "contentHash", "lastModifiedSource", "updatedAt", "versionId"}`.
+    def pull_skill(name, request_options: {})
+      get_json("v1/skills/pull", { name: name }, request_options)
+    end
+
+    # Converges `{ name:, steps: [...], evals:? }`. Inline `evals` are not part
+    # of the flow wire: each converges through {#ensure_eval} after the flow and
+    # is reported as `result["evals"]`; a dry run skips them.
+    #
+    # @param version [Hash, nil] provenance for the version row, `{ label:, notes: }`.
+    # @return [Hash] `{"result", "flowId", "versionId", "contentHash", "evals"?}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_flow(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
+                    expected_remote_hash: nil, version: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, release: release&.to_s, expectedRemoteHash: expected_remote_hash,
+                  version: version_metadata(version) }
+      flow_wire = { "name" => wire["name"], "steps" => wire["steps"] || [] }
+      result = converge_config(FLOW, "v1/flows/ensure", wire, flow_wire, options.compact,
+                               dry_run: dry_run, expect_no_changes: expect_no_changes,
+                               request_options: request_options)
+      inline_evals = Array(wire["evals"])
+      return result if result["result"] == "plan" || inline_evals.empty?
+
+      result.merge("evals" => inline_evals.map { |suite| ensure_eval(suite, request_options: request_options) })
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"flowId", "definition", "contentHash", "lastModifiedSource", "updatedAt", "versionId"}`.
+    def pull_flow(name, request_options: {})
+      get_json("v1/flows/pull", { name: name }, request_options)
+    end
+
+    # Converges `{ name:, description:, toolType:, parametersSchema:, config: }`. Never deletes.
+    #
+    # @return [Hash] `{"result", "toolId", "contentHash"}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_tool(definition, dry_run: false, expect_no_changes: false, on_conflict: nil,
+                    expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(TOOL, "v1/tools/ensure", wire, wire, options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"toolId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_tool(name, request_options: {})
+      get_json("v1/tools/pull", { name: name }, request_options)
+    end
+
+    # Converges `{ name:, type:, behavior:?, inbound:?, outbound:?, status:? }`
+    # as a surface of `product_id`; identity is the name within that product.
+    #
+    # @param product_id [String]
+    # @return [Hash] `{"result", "surfaceId", "contentHash"}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_surface(product_id, definition, dry_run: false, expect_no_changes: false, on_conflict: nil,
+                       expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(SURFACE, surface_path(product_id, "ensure"), wire, wire, options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options,
+                      memo_scope: product_id.to_s,
+                      probe_first: !(wire.key?("inbound") || wire.key?("outbound")))
+    end
+
+    # @param product_id [String]
+    # @param name [String]
+    # @return [Hash] `{"surfaceId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_surface(product_id, name, request_options: {})
+      get_json(surface_path(product_id, "pull"), { name: name }, request_options)
+    end
+
+    # Converges the product row `{ name:, description:?, icon:?, spec:? }`.
+    #
+    # @return [Hash] `{"result", "productId", "contentHash"}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_product(definition, dry_run: false, expect_no_changes: false, on_conflict: nil,
+                       expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(PRODUCT, "v1/products/ensure", wire, wire, options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"productId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_product(name, request_options: {})
+      get_json("v1/products/pull", { name: name }, request_options)
+    end
+
+    # Converges a whole Full Product Object; the server fans out per entity.
+    # Ships the full FPO (no hash probe). Non-atomic: inspect `"hasFailures"`
+    # and `"entities"` and re-run to self-heal.
+    #
+    # @param fpo [Hash]
+    # @param prune [Boolean] remove product-scoped capabilities and surfaces absent from the FPO.
+    # @return [Hash] `{"result", "productId", "contentHash", "entities", "hasFailures"}`.
+    def ensure_fpo(fpo, dry_run: false, on_conflict: nil, prune: false, request_options: {})
+      body = { fpo: fpo }
+      body[:dryRun] = true if dry_run
+      body[:onConflict] = on_conflict.to_s if on_conflict
+      body[:prune] = true if prune
+      config_ensure_request("v1/products/ensure-fpo", body, request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"productId", "fpo", "contentHash", "warnings"?}`.
+    def pull_fpo(name, request_options: {})
+      get_json("v1/products/pull-fpo", { name: name }, request_options)
+    end
+
+    # Converges an eval suite `{ name:, target:, cases:, virtual:, ... }`
+    # (cases carry their merged graders in `expect`). Never executes it.
+    #
+    # @return [Hash] `{"result", "suiteId", "contentHash"}`.
+    # @raise [ArgumentError] for a virtual suite, which has nothing durable to converge.
+    def ensure_eval(definition, request_options: {})
+      wire = config_wire(definition)
+      if wire["virtual"]
+        raise ArgumentError, "Cannot ensure a virtual eval: virtual evals are ephemeral (nothing is persisted to " \
+                             "converge). Remove virtual: true to converge a durable suite, or run it directly."
+      end
+
+      converge_config(EVAL, "v1/eval/ensure", wire, wire, {}, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"suiteId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_eval(name, request_options: {})
+      get_json("v1/eval/pull", { name: name }, request_options)
+    end
+
+    private
+
+    # Round-trips through JSON so Symbol keys and values hash exactly as they will be sent.
+    def config_wire(definition)
+      JSON.parse(JSON.generate(definition.to_h))
+    end
+
+    def skill_wire(wire)
+      manifest = wire["manifest"].is_a?(Hash) ? wire["manifest"] : {}
+      frontmatter = (manifest["frontmatter"] || {}).dup
+      runtype_block = flatten_unknown_extensions(manifest["runtype"])
+      frontmatter["runtype"] = runtype_block unless runtype_block.empty?
+      { "frontmatter" => frontmatter, "body" => manifest["body"] || "" }
+    end
+
+    # Spreads a pulled `unknownExtensions` back to top-level `runtype` keys, as SKILL.md stores them.
+    def flatten_unknown_extensions(runtype_block)
+      return {} unless runtype_block.is_a?(Hash)
+
+      extensions = runtype_block["unknownExtensions"]
+      flattened = runtype_block.except("unknownExtensions")
+      extensions.is_a?(Hash) ? flattened.merge(extensions) : flattened
+    end
+
+    def surface_path(product_id, action)
+      "v1/products/#{URI.encode_uri_component(product_id.to_s)}/surfaces/#{action}"
+    end
+
+    def converge_config(kind, path, wire, sent, options, request_options:, dry_run: false,
+                        expect_no_changes: false, memo_scope: "", probe_first: true)
+      name = wire["name"]
+      raise ArgumentError, "#{kind.label} ensure requires a definition with a non-empty name" unless
+        name.is_a?(String) && !name.empty?
+
+      if dry_run || expect_no_changes
+        plan = config_ensure_request(path, { name: name, definition: sent, dryRun: true, **options },
+                                     request_options)
+        return check_config_plan(kind, plan, name, expect_no_changes)
+      end
+
+      local_hash = kind.hasher.call(wire)
+      memo_key = "#{memo_scope}\0#{name}\0#{local_hash}"
+      probe = { "result" => "definitionRequired" }
+      if probe_first
+        probe = config_ensure_request(
+          path, { name: name, contentHash: config_ensure_memo[memo_key] || local_hash, **options },
+          request_options
+        )
+      end
+      if probe["result"] == "definitionRequired"
+        probe = config_ensure_request(path, { name: name, definition: sent, **options }, request_options)
+        if probe["result"] == "definitionRequired"
+          raise Runtype::Error, "Server reported definitionRequired for a full-definition request"
+        end
+      end
+      config_ensure_memo[memo_key] = probe["contentHash"] if probe["result"] != "plan" && probe["contentHash"]
+      probe
+    end
+
+    def check_config_plan(kind, plan, name, expect_no_changes)
+      raise Runtype::Error, "Expected a plan result from dryRun, got #{plan["result"].inspect}" unless
+        plan["result"] == "plan"
+      if expect_no_changes && kind.drift && (plan["changes"] != "none" || plan["publishPending"] == true)
+        raise Runtype::DriftError.new(plan, name: name, entity: kind.label, pull_hint: kind.pull_hint,
+                                            ensure_hint: kind.ensure_hint)
+      end
+
+      plan
+    end
+
+    # @return [Hash{String => String}] `scope\0name\0localHash` => server hash.
+    def config_ensure_memo
+      @config_ensure_memo ||= {}
+    end
+
+    def config_ensure_request(path, body, request_options)
+      post_json(path, body, request_options)
+    rescue Runtype::APIStatusError => e
+      raise Runtype::EnsureConflictError.from_status_error(e) if Runtype::EnsureConflictError.protocol_conflict?(e)
+
+      raise
+    end
+  end
+end