runtype 0.2.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af0bbf25840f4340b5269585397637edd31012849c0d9bb6228d60818a3999b8
-  data.tar.gz: 7faf081469ffb6891459f53583b38919703705b21dc44e72aa99058ad5d6bdb3
+  metadata.gz: d76301f01717eb2c8c268aa576abea7ab7281c9e333ef117bc8fd2786dffe4a4
+  data.tar.gz: 9e1210dc611fc2db3c7f2f949dbff9eb24cc3f1aeb7e2c8b64a5b62660cd4f8d
 SHA512:
-  metadata.gz: 037faa37e743cb38c72015de37a5c76f5cc1b01288c592abae0bf1f106f431c1fe3401131f4f7cf695c10fbbfbd30db0ca27dff520f16dde6e8279506d6698ff
-  data.tar.gz: 2db93bef84aef75510da3e23895d15a1cf75d640d8023397d2f90925f2f46353dc2c1adc5b34fb92dc061861e4aaccb6a5cdb96171908c6a054997fa133ee793
+  metadata.gz: a24d85ce1007caa25806f38f04b6b3cd5f1f1eb1b0b71b77e3817b464501dfc7cfb151916d9f282a9252dad90018ee39871c1c39a97fab5659e6731289bbbb68
+  data.tar.gz: d909413a2c441648bf3b0387355e0479e549fa556cc4e13fe9ce9a0ac1592e0477066181d12e797868d672cf8f4a0e2f1bd05481a8b8a21f631c6353d5c0d806

data/CHANGELOG.md

@@ -1,7 +1,175 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- c6dee53: Regenerate the Java, Python and Ruby SDK cores from the OpenAPI spec (spec 1228fedfe63e -> 14f6826470f1, output aca7693058e4).
+
+  API changes:
+  - breaking: POST /v1/agent-versions/{agentId}/publish response 200: property "applied" is now optional
+  - breaking: POST /v1/agent-versions/{agentId}/publish response 409<allOf[0]>: property "lastModifiedSource" is now optional
+  - breaking: POST /v1/agents/{id}/execute response 409: anyOf composition changed (0 -> 1 branches)
+  - breaking: POST /v1/agents/{id}/execute response 409: property "candidateCount" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: property "code" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: property "configId" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: property "details" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: property "error" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: property "modelId" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: property "provider" removed
+  - breaking: POST /v1/agents/{id}/execute response 409: type changed object -> anyOf
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]: anyOf composition changed (4 -> 5 branches)
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: property "assetId" removed
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: property "filename" removed
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: property "mimeType" removed
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: property "orgKey" removed
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: property "refKind" removed
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: property "sizeBytes" removed
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>: required property "text" added
+  - breaking: PUT /v1/conversations/{id} request.messages[].content<anyOf[1]>[]<anyOf[3]>.type: enum value "asset_ref" removed
+  - breaking: schema ClientInputDeliveryReceipt: required property "initial" added
+  - breaking: schema InputDeliveryReceipt: required property "initial" added
+  - added: DELETE /v1/agents/{id}/aliases/{alias}/bindings: operation added
+  - added: GET /v1/agent-aliases: operation added
+  - added: GET /v1/agents/{id}/aliases response 200.data[]: required property "bindingNames" added
+  - added: GET /v1/agents/{id}/aliases/{alias} response 200: required property "bindingNames" added
+  - added: GET /v1/agents/{id}/aliases/{alias}/bindings: operation added
+  - added: GET /v1/agents/{id}/deployments response 200.data[]: required property "bindings" added
+  - added: GET /v1/conversations/{id} response 200: property "imported" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: property "author" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: property "createdAt" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: property "id" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: property "metadata" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: property "toolCalls" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: property "toolResults" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: required property "content" added
+  - added: GET /v1/conversations/{id} response 200.messages[]: required property "role" added
+  - added: GET /v1/products/{id}/activity: operation added
+  - added: POST /v1/agent-versions/{agentId}/publish: header parameter "idempotency-key" added
+  - added: POST /v1/agent-versions/{agentId}/publish: header parameter "if-match" added
+  - added: POST /v1/agent-versions/{agentId}/publish: response 412 added
+  - added: POST /v1/agent-versions/{agentId}/publish request: property "deployment" added
+  - added: POST /v1/agent-versions/{agentId}/publish response 409<allOf[0]>: property "expectedVersionId" added
+  - added: POST /v1/agent-versions/{agentId}/publish response 409<allOf[0]>.code: enum value "idempotency_key_reused" added
+  - added: POST /v1/agent-versions/{agentId}/publish response 409<allOf[0]>.code: enum value "rollback_target_mismatch" added
+  - added: POST /v1/agents/{id}/aliases/{alias}/rollback response 200: required property "activePreviewCount" added
+  - added: POST /v1/agents/{id}/aliases/{alias}/rollback response 200: required property "bindingNames" added
+  - added: POST /v1/agents/{id}/aliases/{alias}/rollback response 200: required property "previewLimit" added
+  - added: POST /v1/agents/{id}/execute: response 413 added
+  - added: POST /v1/agents/{id}/execute response 409: anyOf branch "ConversationBusyError" added
+  - added: POST /v1/agents/{id}/execute response 409: anyOf branch "ConversationModifiedError" added
+  - added: POST /v1/agents/ensure: response 429 added
+  - added: POST /v1/conversations: response 200 added
+  - added: POST /v1/conversations: response 404 added
+  - added: POST /v1/conversations request: property "agentId" added
+  - added: POST /v1/conversations request: property "messages" added
+  - added: POST /v1/conversations request: property "source" added
+  - added: POST /v1/conversations response 201: property "imported" added
+  - added: POST /v1/conversations response 201.messages[]: property "author" added
+  - added: POST /v1/conversations response 201.messages[]: property "createdAt" added
+  - … 68 more changes
+
+  SDK surface:
+  - java: 657 public symbols added, 156 removed
+    - removed: `Builder`
+    - removed: `Builder.additionalProperties`
+    - removed: `Builder.additionalProperty`
+    - removed: `Builder.build`
+    - removed: `Builder.content`
+    - removed: `Builder.createdAt`
+    - removed: `Builder.from`
+    - removed: `Builder.id`
+    - removed: `Builder.role`
+    - removed: `ContentStage`
+    - removed: `IdStage`
+    - removed: `PutV1ConversationsIdRequestMessagesItem`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.builder`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.equals`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.getAdditionalProperties`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.getContent`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.getCreatedAt`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.getId`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.getRole`
+    - removed: `PutV1ConversationsIdRequestMessagesItem.hashCode`
+    - … 136 more removed
+  - python: 22 public symbols added, 9 removed
+    - removed: `PutV1ConversationsIdRequestMessagesItem`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItem_AssetRef`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItem_File`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItem_Image`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItem_Text`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItemAssetRef`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItemFile`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItemImage`
+    - removed: `PutV1ConversationsIdRequestMessagesItemContentOneItemText`
+  - ruby: 113 public symbols added, 36 removed
+    - removed: `Conversations`
+    - removed: `PutV1ConversationsIDRequestMessagesItem`
+    - removed: `Runtype`
+    - removed: `Types`
+    - removed: `Conversations`
+    - removed: `PutV1ConversationsIDRequestMessagesItemContent`
+    - removed: `Runtype`
+    - removed: `Types`
+    - removed: `Conversations`
+    - removed: `PutV1ConversationsIDRequestMessagesItemContentOneItem`
+    - removed: `Runtype`
+    - removed: `Types`
+    - removed: `Conversations`
+    - removed: `PutV1ConversationsIDRequestMessagesItemContentOneItemAssetRef`
+    - removed: `Runtype`
+    - removed: `Types`
+    - removed: `Conversations`
+    - removed: `PutV1ConversationsIDRequestMessagesItemContentOneItemAssetRefRefKind`
+    - removed: `Runtype`
+    - removed: `Types`
+    - … 16 more removed
+
+### Patch Changes
+
+- a2839fb: `Runtype::Client.new(timeout:)` now governs generated resource calls, not only the dispatch and streaming paths. The generated `BaseClient` accepts no timeout, so every `client.flows.*`, `client.evals.*` and delegated `client.api.*` call ran under the code generator's 60 second default no matter what the client was given; a synchronous eval run that took 80 seconds always timed out. The documented 600 second default now actually applies, and `request_options: { timeout_in_seconds: n }` overrides it for one call, on a copy of the transport so a client shared across threads is never mutated mid-call.
+
+  A socket timeout inside a generated call is also curated now. The generated methods rescue `Net::HTTPRequestTimeout`, a 408 response class no socket ever raises, so `Net::ReadTimeout` escaped the `Runtype::Error` tree entirely. `Runtype.wrap_errors` and `Runtype::Error.from_generated` translate `Timeout::Error` (which covers open, read and write timeouts) into `Runtype::APITimeoutError` carrying the original message, matching what the streaming path already did.
+
+- ffccd92: `Runtype::Client#archive_agent_alias_everywhere` no longer absorbs an SDK defect
+  as an ordinary per-agent failure row. Its per-row rescue is now the curated
+  `Runtype::Error` tree plus the transport exceptions `Net::HTTP` raises below
+  `Runtype.wrap_errors` (`Timeout::Error`, `OpenSSL::SSL::SSLError`,
+  `SocketError`, `SystemCallError`, `IOError`) — the same set
+  `Runtype::Streaming::Connection` translates. A `NoMethodError` on a malformed
+  generated model, or any other programming error, now aborts the sweep loudly
+  instead of making it look complete with an extra `"failed"` row.
+
+## 0.4.0
+
+### Minor Changes
+
+- fdeed1b: Ruby SDK release-alias parity. `Runtype::Client#ensure_agent(version:)` stamps the version row a converge appends with your own `label:` and `notes:`, which is what the agent page, the deployment receipts and the compare-to-live view key on; omit it and the label stays `"sdk-ensure"` with server-generated notes. It rides the hash probe, the full-definition request and a dry run alike.
+
+  `Runtype::Client#activate_agent_alias(promotion:)` links the source-organization ids and hashes a cross-organization promotion came from onto the deployment receipt, so a production receipt can name the staging version it was promoted from. Provenance only: it authorizes nothing, and the activating credentials alone decide what the activation may do. Takes either key spelling or a `Runtype::Types::AgentDeploymentPromotion`.
+
+  `Runtype::Client#list_agent_aliases_by_name` reads one pointer name across the whole organization (`GET /v1/agent-aliases`), with each agent's revision to quote back as `If-Match`, and `#archive_agent_alias_everywhere` sweeps that name off every agent carrying it — the cleanup a closed pull request runs. Each row is archived under the revision just read, so a concurrent deploy answers 412 instead of racing, and one agent's failure is reported in `"failed"` rather than aborting the rest — transport failures (DNS, TLS, a connection reset) included, since those are raised by `Net::HTTP` and never reach the curated error tree. `dry_run:` reports what would be archived and archives nothing.
+
+  Both `version:` and `promotion:` refuse an unrecognized key with an `ArgumentError` naming the accepted ones, rather than letting the server's strict schemas answer a 400; a hash whose values are all `nil` is treated as omitted, so building one from environment variables that may be absent still works.
+
 All notable changes to the Runtype Ruby SDK are documented here.
 
+## 0.3.0
+
+- Release aliases on `Runtype::Client`: `#list_agent_aliases`, `#get_agent_alias`,
+  `#activate_agent_alias`, `#archive_agent_alias`, `#rollback_agent_alias` and
+  `#list_agent_deployments` wrap the generated `agent_aliases` client with the curated
+  `Runtype::Error` tree. `revision:` is sent as `If-Match` and `idempotency_key:` as
+  `Idempotency-Key`; `version_id` is sent exactly as given, because an alias is never
+  resolved to a version client-side.
+- `Runtype::Client#ensure_agent(deploy:)` saves a version and aims a release alias at
+  it in one call, taking `{ alias: "pr-482" }` or the bare alias name. It rides both
+  the hash probe and the full-definition request. `release:` remains the compatibility
+  spelling of `deploy: { alias: "live" }`; passing both raises an `ArgumentError`
+  carrying the API's own refusal sentence.
+- README: a "Release aliases" section covering the wrappers, dispatching against a
+  pointer, and the cross-organization prepare, validate, evaluate, activate recipe.
+
 ## 0.2.2
 
 - The durable follow from 0.2.1, hardened after review: a buffered follow gives up
@@ -30,7 +198,7 @@ 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
+  `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:`,

data/README.md

@@ -83,11 +83,9 @@ pulled["definition"]   # the canonical wire definition; ensure_agent accepts it
 pulled["lastModifiedSource"]
 ```
 
-Top-level fields take snake_case or the wire's camelCase; nested config (`tools`,
+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
+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
@@ -98,6 +96,146 @@ pass `on_conflict: "overwrite"` to converge over it) or when an
 platform does, over the canonical normalized form (keys ordered as `JSON.stringify`
 emits them, numbers rendered as JavaScript renders them).
 
+## Release aliases
+
+An agent runs an immutable **version**. A named mutable **alias** selects which one:
+`live` is the permanent pointer every unqualified dispatch resolves, and preview
+aliases such as `pr-482` point somewhere else. Every activation appends a
+**deployment receipt**, so the history of what ran is append-only.
+
+```ruby
+client.list_agent_aliases(agent_id)                       # live first, then previews by name
+client.list_agent_aliases(agent_id, include_archived: true, limit: 20, cursor: cursor)
+client.get_agent_alias(agent_id, "live")                  # 404 names the alias; never falls back to live
+
+client.activate_agent_alias(agent_id, "live", version_id: "agv_9",
+                            revision: current.revision,   # sent as If-Match
+                            idempotency_key: "deploy-482",
+                            reason: "ship the pricing fix")
+
+client.rollback_agent_alias(agent_id, "live", steps: 1, revision: current.revision)
+client.archive_agent_alias(agent_id, "pr-482", revision: preview.revision)
+
+client.list_agent_deployments(agent_id, alias_name: "live", limit: 20)
+```
+
+### Closing a pull request
+
+One pointer name usually spans several agents, so the cleanup a closed pull
+request runs is org-wide rather than per agent:
+
+```ruby
+client.list_agent_aliases_by_name("pr-482")            # every agent carrying it, with each revision
+client.archive_agent_alias_everywhere("pr-482", dry_run: true)  # report, archive nothing
+client.archive_agent_alias_everywhere("pr-482")
+```
+
+The sweep archives each pointer under the revision it just read, so a concurrent
+deploy answers 412 instead of racing. One agent's failure is reported rather than
+aborting the rest, transport failures included:
+
+```ruby
+sweep = client.archive_agent_alias_everywhere("pr-482")
+sweep["archived"]  # [{"agentId", "agentName", "revision", "receiptId"}, ...]
+sweep["failed"]    # [{"agentId", "agentName", "error", "code" => "alias_revision_mismatch"}, ...]
+```
+
+`"code"` is the alias plane's refusal code and is absent on a transport failure
+(DNS, TLS, a connection reset), which is reported with its message alone.
+
+Only active pointers are listed, so a second run archives nothing. A dry run
+answers `{"alias", "dryRun" => true, "wouldArchive" => [<row>]}` with the listed
+rows unchanged.
+
+`version_id` is sent exactly as given: the SDK never resolves an alias to a version
+for you. `revision:` is the alias revision you read back from `get_agent_alias`, sent
+as `If-Match`; moving an existing `live` pointer requires it, and a stale value is a
+409 rather than a lost update. Archiving stops a preview from resolving for new
+executions, keeps its history, and does not interrupt runs already admitted; `live`
+cannot be archived. Rollback restores configuration only, not external data or side
+effects.
+
+`ensure_agent` can save and activate in one call. `deploy:` names the alias to aim at
+the version it just saved:
+
+```ruby
+client.ensure_agent(assistant)                              # save a version, live unchanged
+client.ensure_agent(assistant, deploy: { alias: "pr-482" }) # save and aim the preview pointer
+client.ensure_agent(assistant, deploy: "live")              # a bare String names the alias
+```
+
+`release: "publish"` is the older spelling of `deploy: { alias: "live" }`. Passing both
+raises an `ArgumentError` with the same sentence the API answers a 400 with.
+
+`version:` stamps the appended version row with your own provenance, which is what the
+agent page, the receipts and the compare-to-live view key on. Omit it and the label is
+`"sdk-ensure"` with server-generated notes:
+
+```ruby
+client.ensure_agent(assistant, deploy: "live",
+                    version: { label: ENV.fetch("GITHUB_SHA")[0, 7],
+                               notes: "Promoted from CI run #{ENV.fetch("GITHUB_RUN_ID")}" })
+```
+
+Both fields are optional (`label` up to 100 characters, `notes` up to 2000), and a hash
+whose values are all `nil` is treated as omitted rather than refused, so building one
+from environment variables that may be absent still saves.
+
+Dispatch against a pointer instead of pinning a version, and the run resolves it at
+admission:
+
+```ruby
+client.dispatch(agent: { agentId: agent_id }, messages: messages)                    # live
+client.dispatch(agent: { agentId: agent_id, alias: "pr-482" }, messages: messages)   # a preview
+client.dispatch(agent: { agentId: agent_id, versionId: "agv_9" }, messages: messages) # one exact version
+```
+
+### Deploying across organizations
+
+Organizations are isolated, so a staging version id means nothing in production. The
+recipe is prepare, validate the bindings, evaluate, activate, with one client per
+organization and the destination's own ids throughout. Credentials are never copied:
+the destination's connections and secrets are what its runs use.
+
+```ruby
+staging    = Runtype::Client.new(api_key: ENV.fetch("RUNTYPE_STAGING_KEY"))
+production = Runtype::Client.new(api_key: ENV.fetch("RUNTYPE_PRODUCTION_KEY"))
+
+# 1. Prepare. Same portable definition, destination account, no deploy: so live is untouched.
+source = staging.pull_agent("Pricing Assistant")
+prepared = production.ensure_agent(
+  source["definition"], version: { label: ENV.fetch("GITHUB_SHA")[0, 7] }
+)
+agent_id, candidate = prepared["agentId"], prepared["versionId"]
+
+# 2. Validate the bindings in the destination, where the portable refs actually resolve.
+production.pull_agent("Pricing Assistant")["definition"]["tools"]
+live = production.get_agent_alias(agent_id, "live")
+
+# 3. Evaluate that exact version id against a destination suite.
+report = production.evals.run_eval_suite_synchronously(
+  suite_id: "evs_pricing", agent: { versionId: candidate }
+)
+
+# 4. Activate, quoting the revision you just read, and name where this came from.
+production.activate_agent_alias(
+  agent_id, "live", version_id: candidate, revision: live.revision,
+  idempotency_key: "release-#{candidate}", reason: "promoted from staging",
+  promotion: { source_agent_id: source["agentId"], source_version_id: source["versionId"],
+               source_content_hash: source["contentHash"], source_commit: ENV.fetch("GITHUB_SHA") }
+)
+```
+
+`promotion:` is what makes the production receipt name the staging version it came
+from. It is provenance only: it authorizes nothing, and the destination credentials
+alone decide what the activation may do. Every field is optional, and a hash whose
+values are all `nil` is treated as omitted.
+
+Nothing gates step 4 on step 3. `evaluate` reports; it does not hold the pointer. If a
+score should stop a release, branch on `report` yourself before calling
+`activate_agent_alias`. An environment-specific rendering of the definition produces a
+different artifact, so its evaluation evidence does not carry over from staging.
+
 ## Authentication
 
 Pass `api_key:`, or leave it out and the client reads `RUNTYPE_API_KEY`. The base URL
@@ -115,6 +253,26 @@ different accounts or environments can coexist in one process.
 A missing or blank key raises `Runtype::AuthenticationError` at construction, before
 any request goes out.
 
+## Timeouts
+
+`timeout:` is the per-operation socket timeout in seconds, defaulting to 600. It is
+generous on purpose: an execution stream can idle between events while a model is
+thinking, and a synchronous eval run can take minutes. One value governs the dispatch
+and streaming paths and every generated resource call alike.
+
+```ruby
+client = Runtype::Client.new(timeout: 900)            # ten minutes is not enough
+client.evals.run_eval_suite_synchronously(suite_id: "evs_1")   # runs under 900 seconds
+
+# Override for one call, without touching the client other threads are sharing.
+client.flows.list_flows(request_options: { timeout_in_seconds: 5 })
+```
+
+A socket timeout raises `Runtype::APITimeoutError` on the dispatch and streaming
+paths. On a generated resource call it raises the transport's own error, so wrap the
+call in `Runtype.wrap_errors` to get `Runtype::APITimeoutError` there too, the same
+way the curated hierarchy is reached for every other generated failure.
+
 ## Streaming
 
 `dispatch_stream` returns a `Runtype::Streaming::EventStream`, an `Enumerable` of
@@ -216,19 +374,19 @@ loop that exceeds `max_rounds:` raises `Runtype::LocalToolError`.
 
 Everything the client raises descends from `Runtype::Error`.
 
-| Class                               | When                               |
-| ----------------------------------- | ---------------------------------- |
-| `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` |
+| Class                               | When                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| `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
@@ -312,12 +470,19 @@ an empty `GEM_HOME` to prove the packaged layout loads.
 
 The gem is published by `.github/workflows/publish-ruby-sdk.yml` through RubyGems
 trusted publishing (OIDC against the `rubygems` GitHub environment; no API key).
-The SDK sits outside the monorepo's changesets flow, so a release is:
-
-1. Bump `SDK_VERSION` in `lib/runtype/sdk_version.rb` and add a `## <version>`
-   section to `CHANGELOG.md`, in a PR to `staging`.
-2. After it merges, run the workflow from `staging` with that version, first with
-   `dry_run` on, then off:
+The version comes from the monorepo's changesets flow, so a release is:
+
+1. Land a changeset naming `@runtypelabs/ruby-sdk` (an overlay PR writes its
+   own; the Update SDKs bot writes one for every regenerated core, see
+   `docs/claude/sdk-release.md`). Never hand-edit `SDK_VERSION` in
+   `lib/runtype/sdk_version.rb`: it is a mirror of `package.json`, rewritten by
+   `scripts/sync-sdk-versions.mjs` on every Version Packages run, and
+   `pnpm check:release-config` reds on drift.
+2. Merge the Version Packages PR. That bumps `package.json`, mirrors the number
+   into `sdk_version.rb`, and prepends the `## <version>` section to
+   `CHANGELOG.md`.
+3. Run the workflow from `staging` with that version, first with `dry_run` on,
+   then off:
 
    ```bash
    gh workflow run publish-ruby-sdk.yml --ref staging -f version=<version> -f dry_run=true