runtype 0.3.0 → 0.5.0

data/generated/lib/runtype/types/conversation_transcript_message_content_one_item_text.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Types
+    class ConversationTranscriptMessageContentOneItemText < Internal::Types::Model
+      field :text, -> { String }, optional: false, nullable: false
+    end
+  end
+end

data/generated/lib/runtype/types/conversation_transcript_message_role.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Types
+    module ConversationTranscriptMessageRole
+      extend Runtype::Internal::Types::Enum
+
+      SYSTEM = "system"
+      USER = "user"
+      ASSISTANT = "assistant"
+      TOOL = "tool"
+    end
+  end
+end

data/generated/lib/runtype/types/conversation_transcript_message_tool_calls_item.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Types
+    class ConversationTranscriptMessageToolCallsItem < Internal::Types::Model
+      field :args, -> { Internal::Types::Hash[String, Object] }, optional: true, nullable: false
+
+      field :provider_options, -> { Internal::Types::Hash[String, Object] }, optional: true, nullable: false, api_name: "providerOptions"
+
+      field :tool_call_id, -> { String }, optional: false, nullable: false, api_name: "toolCallId"
+
+      field :tool_name, -> { String }, optional: false, nullable: false, api_name: "toolName"
+    end
+  end
+end

data/generated/lib/runtype/types/conversation_transcript_message_tool_results_item.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Types
+    class ConversationTranscriptMessageToolResultsItem < Internal::Types::Model
+      field :provider_options, -> { Internal::Types::Hash[String, Object] }, optional: true, nullable: false, api_name: "providerOptions"
+
+      field :result, -> { Object }, optional: true, nullable: false
+
+      field :tool_call_id, -> { String }, optional: false, nullable: false, api_name: "toolCallId"
+
+      field :tool_name, -> { String }, optional: false, nullable: false, api_name: "toolName"
+    end
+  end
+end

data/generated/lib/runtype.rb

@@ -42,12 +42,17 @@ require_relative "runtype/agent_aliases/types/get_v1agents_id_aliases_response"
 require_relative "runtype/agent_aliases/types/get_v1agents_id_aliases_alias_response"
 require_relative "runtype/agent_aliases/types/put_v1agents_id_aliases_alias_response"
 require_relative "runtype/agent_aliases/types/delete_v1agents_id_aliases_alias_response"
+require_relative "runtype/agent_aliases/types/get_v1agents_id_aliases_alias_bindings_response"
+require_relative "runtype/agent_aliases/types/put_v1agents_id_aliases_alias_bindings_response"
+require_relative "runtype/agent_aliases/types/delete_v1agents_id_aliases_alias_bindings_response"
 require_relative "runtype/agent_aliases/types/post_v1agents_id_aliases_alias_rollback_response"
 require_relative "runtype/agent_aliases/types/get_v1agents_id_deployments_response_data_item"
 require_relative "runtype/agent_aliases/types/get_v1agents_id_deployments_response"
 require_relative "runtype/agent_versions/types/get_v1agent_versions_agent_id_request_type"
 require_relative "runtype/agent_versions/types/get_v1agent_versions_agent_id_response_versions_item"
 require_relative "runtype/agent_versions/types/get_v1agent_versions_agent_id_response"
+require_relative "runtype/agent_versions/types/post_v1agent_versions_agent_id_publish_request_deployment_action"
+require_relative "runtype/agent_versions/types/post_v1agent_versions_agent_id_publish_request_deployment"
 require_relative "runtype/agent_versions/types/post_v1agent_versions_agent_id_publish_request_on_conflict"
 require_relative "runtype/agent_versions/types/post_v1agent_versions_agent_id_publish_response_last_modified_source"
 require_relative "runtype/agent_versions/types/post_v1agent_versions_agent_id_publish_response"
@@ -593,19 +598,25 @@ require_relative "runtype/conversations/types/get_v1conversations_response_pagin
 require_relative "runtype/conversations/types/get_v1conversations_response"
 require_relative "runtype/conversations/types/post_v1conversations_response_schema_warnings_item"
 require_relative "runtype/conversations/types/post_v1conversations_response_source"
+require_relative "runtype/types/conversation_message_author_type"
+require_relative "runtype/types/conversation_message_author"
+require_relative "runtype/types/conversation_transcript_message_content_one_item_text"
+require_relative "runtype/types/conversation_transcript_message_content_one_item_image"
+require_relative "runtype/types/conversation_transcript_message_content_one_item_file"
+require_relative "runtype/types/conversation_transcript_message_content_one_item_reasoning"
+require_relative "runtype/types/conversation_transcript_message_content_one_item_asset_ref_ref_kind"
+require_relative "runtype/types/conversation_transcript_message_content_one_item_asset_ref"
+require_relative "runtype/types/conversation_transcript_message_content_one_item"
+require_relative "runtype/types/conversation_transcript_message_content"
+require_relative "runtype/types/conversation_transcript_message_role"
+require_relative "runtype/types/conversation_transcript_message_tool_calls_item"
+require_relative "runtype/types/conversation_transcript_message_tool_results_item"
+require_relative "runtype/types/conversation_transcript_message"
 require_relative "runtype/conversations/types/post_v1conversations_response"
 require_relative "runtype/conversations/types/get_v1conversations_id_response_schema_warnings_item"
 require_relative "runtype/conversations/types/get_v1conversations_id_response_source"
 require_relative "runtype/conversations/types/get_v1conversations_id_response"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content_one_item_text"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content_one_item_image"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content_one_item_file"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content_one_item_asset_ref_ref_kind"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content_one_item_asset_ref"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content_one_item"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_content"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item_role"
-require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_item"
+require_relative "runtype/conversations/types/put_v1conversations_id_request_messages_mode"
 require_relative "runtype/conversations/types/put_v1conversations_id_response_schema_warnings_item"
 require_relative "runtype/conversations/types/put_v1conversations_id_response_source"
 require_relative "runtype/conversations/types/put_v1conversations_id_response"
@@ -715,6 +726,7 @@ require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_credential
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_credential_proxies_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_end_user"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_flow"
+require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_history"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_identity_proof"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_content_one_item_text"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_content_one_item_image"
@@ -723,6 +735,8 @@ require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_i
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_content_one_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_content"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_role"
+require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_tool_calls_item"
+require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item_tool_results_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_messages_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_options_environment"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_zero_options_flow_mode"
@@ -815,6 +829,7 @@ require_relative "runtype/dispatch/types/post_v1dispatch_request_one_credential_
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_credential_proxies_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_end_user"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_flow"
+require_relative "runtype/dispatch/types/post_v1dispatch_request_one_history"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_identity_proof"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_content_one_item_text"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_content_one_item_image"
@@ -823,6 +838,8 @@ require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_it
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_content_one_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_content"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_role"
+require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_tool_calls_item"
+require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item_tool_results_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_messages_item"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_options_environment"
 require_relative "runtype/dispatch/types/post_v1dispatch_request_one_options_flow_mode"
@@ -1215,6 +1232,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_mid_conversation_system_messages"
 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"
@@ -1251,6 +1269,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_mid_conversation_system_messages"
 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"
@@ -1342,6 +1361,24 @@ require_relative "runtype/products/types/put_v1products_id_request_spec_tech_sta
 require_relative "runtype/products/types/put_v1products_id_request_spec"
 require_relative "runtype/products/types/put_v1products_id_response"
 require_relative "runtype/products/types/delete_v1products_id_response"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item_agent_target_resolution"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item_agent_version"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item_execution_mode"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item_notification_mode"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item_pending_approval"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item_status"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_data_item"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item_error"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_agents_item"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item_data_item_agent_mode"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item_data_item_available_fields_metadata_schema"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item_data_item_available_fields"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item_data_item"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item_error"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item_source"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data_surfaces_item"
+require_relative "runtype/products/types/get_v1products_id_activity_response_data"
+require_relative "runtype/products/types/get_v1products_id_activity_response"
 require_relative "runtype/products/types/post_v1products_id_capabilities_response"
 require_relative "runtype/products/types/put_v1products_id_capabilities_capability_id_response"
 require_relative "runtype/products/types/delete_v1products_id_capabilities_capability_id_response"
@@ -1564,6 +1601,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_mid_conversation_system_messages"
 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"
@@ -1916,16 +1954,17 @@ require_relative "runtype/types/conflict_error_body_last_modified_source"
 require_relative "runtype/types/conflict_error_body_organization_model_config_migrated"
 require_relative "runtype/types/conflict_error_body_organization_connection_migrated"
 require_relative "runtype/types/conflict_error_body"
-require_relative "runtype/types/not_found_error_body_code"
-require_relative "runtype/types/not_found_error_body"
 require_relative "runtype/types/precondition_failed_error_body_code"
 require_relative "runtype/types/error_details_item"
 require_relative "runtype/types/error"
 require_relative "runtype/types/precondition_failed_error_body"
+require_relative "runtype/types/not_found_error_body_code"
+require_relative "runtype/types/not_found_error_body"
 require_relative "runtype/types/unprocessable_entity_error_body_code"
 require_relative "runtype/types/unprocessable_entity_error_body"
-require_relative "runtype/types/conflict_error_body_organization_model_config_needs_configuration"
 require_relative "runtype/types/bad_request_error_body_code"
+require_relative "runtype/types/conflict_error_body_candidate_count_code"
+require_relative "runtype/types/conflict_error_body_candidate_count"
 require_relative "runtype/types/service_unavailable_error_body_code"
 require_relative "runtype/types/service_unavailable_error_body"
 require_relative "runtype/types/forbidden_error_body_code"
@@ -1947,6 +1986,7 @@ require_relative "runtype/types/payment_required_error_body"
 require_relative "runtype/types/forbidden_error_body_error"
 require_relative "runtype/types/not_implemented_error_body_code"
 require_relative "runtype/types/not_implemented_error_body"
+require_relative "runtype/types/conflict_error_body_organization_model_config_needs_configuration"
 require_relative "runtype/types/bad_request_error_body_error"
 require_relative "runtype/types/internal_server_error_body_error"
 require_relative "runtype/types/internal_server_error_body_errors_item"
@@ -2121,6 +2161,9 @@ require_relative "runtype/types/client_input_delivery_receipt"
 require_relative "runtype/types/conversation_busy_error_code"
 require_relative "runtype/types/conversation_busy_error_phase"
 require_relative "runtype/types/conversation_busy_error"
+require_relative "runtype/types/conversation_modified_error_code"
+require_relative "runtype/types/conversation_modified_error"
+require_relative "runtype/types/conversation_source"
 require_relative "runtype/types/daily_usage_response_daily_execution_cap_reason"
 require_relative "runtype/types/daily_usage_response_daily"
 require_relative "runtype/types/daily_usage_response_monthly_execution_cap_reason"
@@ -2454,6 +2497,9 @@ require_relative "runtype/agent_aliases/types/get_v1agents_id_aliases_request"
 require_relative "runtype/agent_aliases/types/get_v1agents_id_aliases_alias_request"
 require_relative "runtype/agent_aliases/types/put_v1agents_id_aliases_alias_request"
 require_relative "runtype/agent_aliases/types/delete_v1agents_id_aliases_alias_request"
+require_relative "runtype/agent_aliases/types/get_v1agents_id_aliases_alias_bindings_request"
+require_relative "runtype/agent_aliases/types/put_v1agents_id_aliases_alias_bindings_request"
+require_relative "runtype/agent_aliases/types/delete_v1agents_id_aliases_alias_bindings_request"
 require_relative "runtype/agent_aliases/types/post_v1agents_id_aliases_alias_rollback_request"
 require_relative "runtype/agent_aliases/types/get_v1agents_id_deployments_request"
 require_relative "runtype/agent_versions/client"
@@ -2728,6 +2774,7 @@ require_relative "runtype/products/types/get_v1products_pull_fpo_request"
 require_relative "runtype/products/types/get_v1products_id_request"
 require_relative "runtype/products/types/put_v1products_id_request"
 require_relative "runtype/products/types/delete_v1products_id_request"
+require_relative "runtype/products/types/get_v1products_id_activity_request"
 require_relative "runtype/products/types/post_v1products_id_capabilities_request"
 require_relative "runtype/products/types/put_v1products_id_capabilities_capability_id_request"
 require_relative "runtype/products/types/delete_v1products_id_capabilities_capability_id_request"

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
@@ -35,6 +39,9 @@ module Runtype
     #   both `release:` and `deploy:` to save without activating.
     # @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 request_options [Hash] see {Runtype::Client#dispatch}.
     # @return [Hash] `{"result" => "unchanged"|"created"|"updated", "agentId",
     #   "versionId", "contentHash"}`, or for a dry run `{"result" => "plan",
@@ -44,9 +51,10 @@ module Runtype
     #   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.
+    # @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, request_options: {})
       raise ArgumentError, RELEASE_DEPLOY_CONFLICT_MESSAGE if release && deploy
 
       definition = Runtype::AgentDefinition.from(definition)
@@ -54,7 +62,8 @@ 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)
       }.compact
 
       if dry_run || expect_no_changes
@@ -115,6 +124,29 @@ module Runtype
       { alias: name.to_s }
     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
     #   hot process pays the probe once per definition.
     def ensure_memo

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

@@ -53,7 +53,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 +82,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 +198,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/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
@@ -235,7 +245,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 +255,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