smith-agents 0.11.0 → 0.12.0

data/CHANGELOG.md

@@ -4,6 +4,704 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
+## [0.12.0] - 2026-10-11
+
+### Upgrade notes
+
+- `execute` reads `mode:` as the call mode (`:sync`, `:batch`, or a callable)
+  and `stream:` as a stream name; neither stays in `agent_opts`, and any other
+  `mode:` value raises `Smith::WorkflowError` at declaration.
+
+- The artifact store must be configured: outside `test_mode`, storing or
+  reading an artifact with no `artifact_store` raises
+  `Smith::ArtifactStoreMissing` instead of using a store in process memory
+  (a run that keeps no artifacts needs none). Set `config.artifact_store` to
+  `:s3`, `:active_record`, `:file` or `:memory` (with
+  `config.artifact_options`), or a store; `smith doctor` reports a missing,
+  unusable or process-local store, and the install templates no longer write
+  `Smith::Artifacts::Memory.new`.
+- Artifact stores take bytes: `store` refuses anything but a String with a
+  `TypeError` (Memory used to keep any object, and File wrote its `inspect`),
+  so serialize first (`JSON.generate`). A store class now gets built with
+  `artifact_options` unless the class itself stores and fetches. A tenant
+  `namespace:` must be letters, digits, `-` and `_`, and
+  `artifact_tenant_isolation` and `artifact_retention` now apply to every
+  built-in store. `Memory#delete` drops one run's claim when given its
+  `execution_namespace:`; the File store's refs are random UUIDs, as before.
+
+- `Smith::EXECUTION_SEMANTICS_VERSION` is now `"7"`: routing, context writes,
+  restore admission, nested failure and retry semantics changed, and durable
+  composite plans may carry content parts, which an earlier build would send
+  as JSON text. Hosts that
+  fold it into definition digests or cache keys see new values, and durable
+  composite plans prepared under 0.11.0 are refused by their integrity check.
+  Drain or clear in-flight persisted runs before upgrading.
+- Token and cost accounting changed too (see Changed): cache tokens count in
+  totals and budgets, cached input on the OpenAI Responses path is priced at
+  the cache-read rate, and completed tool-loop rounds before a failure settle
+  into budgets. A run in flight across the upgrade mixes the two accountings.
+- OpenAI Responses calls cost less on upgrade unless the catalog sets
+  `cache_read_cost_per_token`: their cached input was priced at the full input
+  rate and is now priced at the cache-read rate, 0 when unset.
+- `append_session_messages!` now admits only the roles `user`, `assistant` and
+  `tool`. A host that admitted system notes should put that text in
+  `seed_messages`, the agent's instructions or an `inject_state` formatter. A
+  restored payload must hold only `system`, `user`, `assistant` and `tool`
+  messages; one written earlier may hold a system message the host admitted,
+  which still reaches agents, so rebuild such sessions to rely on the new rule.
+- An agent with no model and no fallback models now fails its step with a
+  `Smith::WorkflowError` instead of returning nil, and runtime readiness reports
+  `:agent_without_model` as an error. Give placeholder agents a model (and a
+  stubbed chat in tests). An agent with fallback models but no primary model
+  used to be skipped the same way and now runs on its fallbacks.
+- A response cut off at its output limit, a refused response, and a structured
+  output that does not parse to a JSON object now fail the step
+  (`Smith::OutputTruncated`, `Smith::OutputRefused`, `Smith::OutputInvalid`)
+  instead of passing on as the output; `on_truncation :accept` keeps the old
+  behavior for cut-off responses. These errors are not `AgentError`s, so a
+  `rescue Smith::AgentError` no longer catches such a failure. An agent's
+  `after_completion` now runs before the structured-output checks, and does not
+  run for a refused or cut-off response.
+
+### Added
+
+- Durable artifact stores, configured like workflow state:
+  `config.artifact_store = :s3` (AWS S3, Cloudflare R2 and other
+  S3-compatible buckets, through the host's `aws-sdk-s3` or `client:`) or
+  `:active_record` (a host table), with `config.artifact_options`; the store
+  may also be a store class built with the options. Every built-in store
+  records which run stored each ref (`stored_by?`) and can `delete`, and
+  `smith doctor` checks the store.
+- Content parts. `Smith::Message.user`, `.assistant` and `.system` take a String
+  or `Smith::Content` parts (`text`, and `document` and `image`, which name an
+  artifact of the run and a media type) in a step's `input:`; seed messages
+  take text parts, and only user messages take documents and images.
+  Anthropic gets native blocks with `cache_control` on parts marked
+  `cache: true` (at most 4 breakpoints per request, the chat's own included);
+  other providers get the parts in order as text with the files attached where
+  they stand, and a model that takes no such content passes the step to the
+  next in the chain. Documents and images are read once per call, only from a
+  store that records which run stored them, and checked against their media
+  type, a 24 MiB document and 5 MiB image bound, and a 32 MiB request bound;
+  any failure raises `Smith::ContentUnavailable` before the call. A message
+  with parts carries `"parts" => true`, which no agent output or
+  host-admitted message can carry, and a restored session holds parts only in
+  its seed messages. A child run may read its parent's artifacts and those of
+  the parent's nearest ancestors (`Smith::ChildRun#artifact_namespaces`, which
+  a queueing launcher passes to the job like `untrusted_keys`; persisted with
+  the child as `inherited_artifact_namespaces`).
+- Durable retry. `retry_on ..., durable: true` waits out each backoff as a
+  wait of the run (`awaiting.kind == :retry`, due when the backoff ends)
+  instead of sleeping in the worker. `expire_wait!` past the deadline ends the
+  wait without a step, and the host continues the run, which makes the next
+  attempt under the recorded attempt number and key generation; the pending
+  retry persists (`pending_retry`, shown as `awaiting.attempt` and
+  `awaiting.error`) until the step ends without a wait, so a crash makes the
+  same attempt again under the same keys (in strict mode, the restore of a run
+  caught in it raises `Smith::StepInProgressOnRestore`). No retry wait is
+  entered past the deadline, after a tool ran, or for a backoff that does not
+  end within the persistence TTL, which runtime readiness reports
+  (`:durable_retry_outlasts_ttl`). `durable:` needs 2 attempts, a positive
+  backoff and `on_failure` (so a last failure settles the run rather than
+  being made again by a job that runs again), and is refused on await, delay,
+  parallel, fan_out, optimize and orchestrate steps; graph inspection shows it, and runtime readiness reports
+  an in-process child with a durable retry (a nested workflow, or a child run
+  the launcher runs inline) as `:nested_workflow_waits`. Split-step
+  persistence refuses a step with a durable retry. Traces gain the outcomes
+  `:retrying` and `:retry_due`.
+- Streaming steps. `execute Agent, stream: :name` sends the reply's text, as
+  the model writes it, to a sink the host registers in
+  `Smith.config.stream_sinks`: a callable that takes the step's info
+  (`stream`, a frozen copy of the `execution_key`, `transition`) when the step
+  starts and returns that step's sink, or nil to stream nothing, so concurrent
+  runs never share a sink. A sink defines any of `start(info)` per provider
+  call (with the attempt, model and provider), `delta(text)` per text chunk
+  (not tool calls, thinking or `<think>` text, which `Smith::Streaming::ThinkTags`
+  keeps out as RubyLLM keeps it out of the message), `reset(reason)` when
+  Smith discards the text sent (`:retry`, `:fallback`, `:truncation`,
+  `:repair`; and `:retry_wait`, always, when a durable retry waits),
+  `finish(output)` with the accepted output (after guardrails, the output
+  contract and `output_to:`, and in a stored run once `persist!` has stored
+  the step; a store that fails gives `fail` with its error) and
+  `fail(error_class)`. A sink or sink callable that raises (a `ScriptError`
+  included) is logged by error class and the step goes on; an unregistered
+  name fails the step before its call (`Smith::StreamSinkMissing`). The text is
+  a draft until `finish`. `Smith::Streaming::JsonField#push` returns the text
+  each delta adds to one top-level string field of streamed JSON (keys read as
+  JSON reads them), in linear time. Stop reasons and message ids are read from
+  the stream itself (`Smith::Providers::StreamFacts`, prepended on RubyLLM's
+  Anthropic, OpenAI, Gemini, OpenRouter and Bedrock chunk builders with each
+  one's visibility kept, inherited by their subclasses, and on
+  `RubyLLM::Provider#complete` to tell a tool loop's requests apart), from the
+  step's own provider only (a tool's own RubyLLM call is not read), per
+  request, in fiber storage; each usage entry keeps its response's facts and
+  `mode: :stream`, so cut-off and refused replies are handled and recorded as
+  without streaming. A streamed reply with no stop reason counts as cut off:
+  `output_limit_reached` when its output tokens reached the request's limit,
+  else `stream_incomplete`. Streaming changes nothing durable, and a replayed
+  step streams again. `stream:` is refused on a parallel step; graph
+  inspection shows it, and runtime readiness reports a missing sink
+  (`:stream_sink_missing`) and an agent whose calls go to the Responses API,
+  which does not stream (`:stream_whole_replies`, decided as Smith's tool
+  routing decides at runtime: `Smith::Models::ToolRouting.responses?`).
+- Batch mode. `execute Agent, mode: :batch` (or `:sync`, or a callable of the
+  context and the step attempt returning one), and the same on `fan_out`,
+  sends the step's requests through a provider's batch API. Smith prepares
+  each call as a synchronous one, admits it against the budget, captures the
+  exact request at RubyLLM's `sync_response` (`Smith::Providers::BatchExchange`,
+  bound to the call's own provider object; the connection's credentials never
+  leave it), and hands it to `Smith.config.batch_queue.enqueue(custom_id:,
+  await_token:, request:, execution_key:)`; the run waits on `:batch_result`
+  (kind `:batch`, 25 hours) with its `pending_batch` recorded. The host
+  submits, polls and collects with `Smith::Providers::Anthropic::Batches`
+  (`submit`, `status`, `results`, `cancel`; no connection retries, so a batch
+  is never submitted twice; the connection's own headers win over a request's)
+  and resumes the run once with `{custom_id => result}`, each result's message
+  checked against the provider's reply shape. The requests are queued only once
+  the step's attempt has ended without error; `pending_batch` keeps each
+  request's digest. A call that renders another request by the time its
+  result comes (a date in its prompt, data read afresh) does what its step's
+  `on_request_change:` says: `:keep` (the default) takes the result, its
+  `:provider_call` trace saying `request_changed: true`; `:resend` sends the
+  request as rendered now over the wire; `:fail` raises
+  `Smith::BatchRequestChanged` (an `AgentError`, which `retry_on` may retry).
+  A result set aside is charged as a `:failed_attempt`. The step runs again at its attempt, each call
+  of that attempt (only) taking its result through RubyLLM's own parser, and a
+  succeeded result no call took (a cancelled fan-out branch), priced under the id RubyLLM
+  resolves its agent's model to, is charged as a
+  `:failed_attempt`; in strict mode the completion runs as a marked step. A
+  batch step in an in-process child fails before capture. Usage with
+  `mode: :batch` priced
+  with `batch_discount` and charged even past a budget
+  (`Budget::Ledger#reserve_spent!`), output checks, follow-up calls over the
+  wire, guardrails and `output_to:` as after a synchronous call. A refused
+  request raises `Smith::BatchRequestInvalid`; a failed, canceled, expired or
+  missing result raises `Smith::BatchResultFailed`, which `retry_on` sends
+  again. A missing queue raises `Smith::BatchQueueMissing`, and a provider
+  without a batch interface in Smith (only Anthropic has one) or an agent with
+  tools `Smith::BatchModeUnavailable`, before anything is sent. A batch step
+  needs `on_failure` and cannot stream or be `parallel:`; graph inspection
+  shows the mode, and runtime readiness reports `:batch_queue_missing`,
+  `:batch_unavailable` and an in-process child with a batch step.
+- A step that runs inside another run's step (an inline child run) scopes its
+  artifacts over the configured store itself, not over the outer run's
+  scoped view, through which it could read nothing of its own.
+- A run's scoped artifact reads check, with a store that records it
+  (`stored_by?`, added to `Smith::Artifacts::Memory` and
+  `Smith::Artifacts::File`), that one of the runs it may read stored the ref,
+  not only the ref's prefix. `Smith::Artifacts::File` no longer reads a ref
+  outside its directory or another tenant's.
+- `Smith::Workflow::Wait` gains `attempt` and `error` (nil except for a retry
+  wait). A wait as long as the persistence TTL is now refused too (it was
+  refused only when longer), since the stored run would expire as it ends.
+- Child runs. `map items, workflow:, max_items:, input:, timeout:, into:,
+  collect:, on_item_failure:` launches a run of its own per item and waits,
+  bounded by `timeout:`, for the host to resume the parent with
+  `resume!(key, event: :children, token:, payload:)` and one
+  `Smith::ChildRun.result` entry per child; `call workflow, input:, timeout:,
+  into:` is a map of one whose `into:` gets the child's output; `spawn items,
+  workflow:, max_items:, input:` launches and continues. Runs start through
+  `Smith.config.run_launcher.launch(children:, parent_key:, await_token:)`,
+  which must be idempotent on `child.key` (the step's token and the child's
+  ref, the index of its item), so a replayed step launches the same children
+  and two steps never share a key.
+  `Smith::Launchers::Inline` (`inline?` true, the only kind of launcher whose
+  return value is taken as results) runs them in process. More than
+  `max_items` fails the step before anything launches; results that do not
+  match the number of children launched raise to the host and leave the run
+  waiting; `collect:` writes outputs, states or counts; `on_item_failure:
+  :fail` fails the step with `Smith::ChildRunsFailed` (failure family
+  `child_runs_failed`) and needs `on_failure`. No map, call or spawn takes
+  `retry_on`, and split-step persistence does not prepare them. A child gets
+  only what `input:` returns and keeps any of its parent's untrusted keys
+  passed under the same name, persisted with it as `inherited_untrusted_keys`.
+  Graph inspection shows `kind: :map`, `:call` or `:spawn` with the child and
+  its bounds; runtime readiness walks child workflows, reports
+  `:run_launcher_missing`, flags an in-process nested workflow that reaches a
+  map, call or spawn, and warns of a child agent that reads a key the parent
+  marks untrusted.
+- Output integrity. Smith reads each response's stop reason (OpenAI's
+  message-level refusals and Gemini's prompt blocks included) as cut off or
+  refused. A cut-off response raises `Smith::OutputTruncated` unless the agent
+  declares `on_truncation :accept` or `on_truncation retry_with:
+  { max_tokens: n }` (one more call on the same model, with the limit mapped to
+  the provider's own parameter, made only when it is larger than the request
+  had and the response did not run out of context); a refused one raises
+  `Smith::OutputRefused` unless the agent declares
+  `on_refusal fallback: "provider/model"` (one call on that model). A
+  structured output (`output_schema`, or a static RubyLLM `schema`) that is not
+  a JSON object, breaks a schema constraint, or fails `output_contract` (whose
+  `call(hash)` returns true, false, or a result answering `success?` and
+  `errors`) goes back to the model with its problems up to `output_repairs`
+  times (default 1), then raises `Smith::OutputInvalid` with at most 20 problems
+  as "path: problem" lines. No follow-up call is made once a tool has run in
+  the step or the step's reserved budget is spent, and a follow-up that fails
+  raises the output error with the provider's error as its cause. For
+  Anthropic, Smith sends the schema without the numeric, string-length and
+  array-size constraints it rejects, with `additionalProperties: false` on
+  every object, refuses an object that allows other properties or declares
+  none (runtime readiness reports `:output_schema_unsupported`), and checks
+  those constraints on the parsed output for every provider. The three errors
+  share the failure family `output_failure` (in durable composite branches
+  too), persist and restore with their details, and are not retryable. Every
+  response is billed and settles into budgets, and a rejected one leaves an
+  `:output_rejected` trace.
+- Usage carries prompt-cache, thinking and response facts. Each provider
+  response's usage (`Smith::Agent::ProviderUsage`), each `UsageEntry`, each
+  `AgentResult`, and the `:provider_call` trace gain `cache_read_tokens`,
+  `cache_write_tokens`, `thinking_tokens`, `stop_reason`, and
+  `provider_message_id`; usage entries also gain `mode` (`:sync` for every call
+  today; streaming and batch steps will record theirs). `input_tokens` keeps
+  meaning uncached input, as RubyLLM reports every provider; the cache counts
+  sit beside it, and `thinking_tokens` are already inside `output_tokens`.
+  `stop_reason` and `provider_message_id` are read from the raw response body
+  of Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, Gemini and
+  Bedrock Converse, each recognized by its own marker (for example
+  `"object" => "response"`); any other body gives neither, and a body that
+  cannot be read never fails the call. They are bounded to 256 bytes and are
+  those of the last response of a tool loop, even when that response reported
+  no usage. Each is omitted when the provider did not report it (RubyLLM's
+  OpenAI adapters report a cache write count of 0): `UsageEntry#to_h` and
+  `ProviderUsage#to_h` leave nil optional members out, so entries written by
+  earlier versions re-serialize byte-identically. Usage entries also gain
+  `mode`, set only for streamed and batch calls (later in this release), so an
+  ordinary call's entry keeps its earlier shape. `:token_usage` and `:cost`
+  traces carry the cache counts too, and `:cost` adds `cache_unpriced: true`
+  when the invocation's cache tokens were priced at 0 for lack of a rate. Hosts
+  with a `trace_fields` allowlist must add the new keys to receive them.
+- Pricing catalogs accept `cache_read_cost_per_token` and
+  `cache_write_cost_per_token` on an entry or a tier (a tier without its own
+  uses the entry's), and `batch_discount` (at least 0 and below 1) on an entry,
+  applied to the whole cost of a call made in batch mode. They are configured
+  per catalog and count as 0 when absent, so a call is never left unpriced for
+  lack of them. `Smith::Pricing.compute_cost` takes `cache_read_tokens:`,
+  `cache_write_tokens:` and `mode:` (defaults 0, 0, `:sync`) and treats a count
+  that is not a non-negative Integer as 0, so it still never raises. Batch mode
+  is priced only through `compute_cost(mode: :batch)` until batch steps ship.
+- Step isolation. `input: ->(ctx) { [...] }` on `execute`, `route`,
+  `fan_out`, `optimize` and `orchestrate` gives a step its own messages (at
+  most 100, user and assistant roles only, with content, bounded like session
+  messages) in place of the session transcript. `output_to: :key` writes the
+  step's output to the context instead of the transcript, JSON-shaped, once the
+  step completes; a key an explicit persist list leaves out is refused before
+  the step runs, and validation reports `:output_to_not_persisted` (and
+  `:await_into_not_persisted` for an await's `into:`). A compute step's
+  `last_output` is the latest step output wherever it went, and the next
+  shared agent step still gets the continuation turn after the transcript's
+  last output. `session :isolated` on a workflow keeps no transcript for
+  agents: every agent step must declare `input:`, outputs are not appended,
+  and `inject_state` never runs. Graph inspection shows `input` and
+  `output_to`; validation reports `:isolated_step_without_input` and warns
+  with `:isolated_workflow_nests_shared_session`.
+- `untrusted :key` on a `Smith::Context` keeps a key from `inject_state`
+  formatters and the `seed_messages` builder, and refuses an agent that names
+  it in `inputs`, in the workflow and in any workflow it nests (runtime
+  readiness reports `:untrusted_agent_input` and
+  `:nested_untrusted_agent_input`); reserved input names are not checked, and
+  `untrusted :auto` is refused. `Smith::Untrusted.wrap(text, source:)`
+  delimits outside content with a boundary the text cannot guess, derived
+  inside a step so a re-prepared step input is identical, and marks role
+  labels after any line break, and look-alike untrusted tags, as quoted text.
+- Durable, bounded waits. `await event, into:, timeout:` waits for an event the
+  host delivers with `Workflow.resume!(key, event:, token:, payload:)`, which
+  writes the payload to the context key `into:` and completes the step;
+  `delay seconds` waits for the time alone. `timeout:` is required (seconds,
+  or a callable of the context), and an await must declare `on_timeout` or
+  `on_failure`; `expire_wait!(key, token:, now:)` past the deadline takes
+  `on_timeout` (with a `StepCompleted` ending in the await's own state) or
+  `on_failure` with the new `Smith::WaitTimedOut` (failure family
+  `wait_timed_out`, restored with its details). An await's optional block runs
+  on entry with a `Smith::Workflow::AwaitStep` (`await_token`, `read_context`,
+  `idempotency_key`, `resolve!`). Entering a wait is not a step: `advance!`
+  returns nil, `run!` and `run_persisted!` stop, the run is never terminal,
+  and step counts and `max_transitions` do not move. `waiting?` and `awaiting`
+  (a `Smith::Workflow::Wait`) let the host index waits and schedule expiry;
+  Smith never polls or wakes a run. The class methods store the run with the
+  version check, require an adapter with `store_versioned`, and return
+  `:resumed`, `:failed`, `:expired`, `:not_due`, `:missing` or `:stale`. A
+  reply that arrives before its wait is stored completes the await at once
+  when the token is the one the run is entering it with, and the entering
+  process loses its next store. One completion at a time claims a wait on an
+  instance. A wait longer than the persistence TTL is refused on entry, and
+  `stuck_for?` treats a waiting run as stuck only past its deadline. Graph
+  inspection shows `kind: :await` or `:delay`, the wait and
+  `timeout_transition`, and runtime readiness reports a nested workflow that
+  reaches a wait (`:nested_workflow_waits`). Split-step persistence refuses
+  wait steps, and an in-process nested workflow that reaches a wait fails its
+  parent's step. `Workflow.transition_named` finds a transition by the String
+  form of its name.
+- Idempotency keys for requests a step sends outside the system.
+  `step.idempotency_key(scope = nil)` in `compute` and `run` steps,
+  `idempotency_key(scope)` inside a `Smith::Tool`'s `perform`, and
+  `Smith::IdempotencyKey.current(scope = nil)` for host code called from a
+  running step return 64 lowercase hex characters (a SHA-256). A key is the
+  same on every attempt of the step and after a restore, and unique to the
+  run, the step's position (step number and transition, then any nested
+  workflow step, parallel or fan-out branch, durable composite branch,
+  optimizer round and role, or orchestrator round and worker task, a task
+  being named by its content), the tool's `name` and the scope. Scopes are
+  built from Strings, Symbols, numbers (a whole Float counts as the
+  Integer), booleans, `nil`, Arrays and Hashes, within 32 levels and 100,000
+  values; NaN, Infinity and other objects raise `ArgumentError`. Outside a
+  running step, and in event handlers and `on_step` callbacks, they raise
+  `Smith::WorkflowError`. Keys survive a crash replay when the run was
+  checkpointed before the step, as `advance_persisted!` and `run_persisted!`
+  do.
+- `retry_on ..., new_idempotency_key_on: [ErrorClass]` and
+  `step.fail!(..., new_idempotency_key: true)` declare that a failed attempt's
+  own requests took no effect, so the attempts after it use new keys; every
+  other retry keeps them. `fail!`'s flag counts only for the step that raised
+  it, never for an enclosing workflow's retry. `new_idempotency_key_on:` must
+  name classes the policy retries, each once, refuses retry-forbidden classes,
+  is refused on nested workflow, parallel, fan-out, optimize and orchestrate
+  transitions, and shows in graph inspection's retry policy when declared.
+  `DeterministicStepFailure#new_idempotency_key` and `#idempotency_scope`, and
+  `DeterministicStep#attempt` (the attempt under way, from 1).
+- `UsageEntry#total_tokens`, `AgentResult#total_tokens`,
+  `AgentResult#billable_tokens` (every known count, which budgets settle) and
+  `ProviderUsage#total_input_tokens`. `Agent::Completion#usage` (the whole
+  completion's `ProviderUsage`), `AgentResult.usage_details`,
+  `AgentResult::USAGE_DETAIL_MEMBERS` and `UsageEntry::OPTIONAL_MEMBERS` are
+  public.
+- Response memo: `Smith.config.response_memo` (`fetch(key)`,
+  `store(key, record)`) keeps what a step's provider calls got, so a step
+  replayed after its process died reuses it instead of paying again. Each
+  call is keyed by its position's idempotency scope, the attempts it runs
+  under (enclosing runs' too), its attempt index, its place among the
+  attempt's calls and a digest of its request (a changed request misses).
+  Its record (version 1) holds the messages it added (replies, structured
+  ones too, with their usage and facts, a stream's included; tool calls and
+  results), stored after each round's tool results and when it ends. A
+  replayed call that ended sends nothing (its `:provider_call` trace says
+  `memo: true`, its usage is recorded once); one that had not continues from
+  its tools' results. Kept tool results count as tools the step ran. A memo
+  never fails a step: a record Smith does not keep is ignored, errors are
+  logged by class.
+- Budget ledgers: `budget_ledger(*scope_keys) { |scope| ... }` names the
+  host's ledger for a run (an account's spend across runs, say). Its scope is
+  the values the keys have in the run's trusted context when it is created,
+  kept with the run (`budget_ledger_scope`); Smith builds the ledger at the
+  run's first request, never persists it, and never needs it to restore a
+  run. A call's first request over the wire (each fallback model, each
+  follow-up, streamed or not, OpenAI's Responses route included) is held on
+  it before it is sent: `reserve!(amount, key:, expires_at:)`, admitted only
+  by `true`, then `reconcile!(key, amount)` with what it spent (its hold, when
+  it answered without usage or its stream failed part way), or
+  `release!(key)` when it failed before anything came back. A hold
+  (`Smith::Budget::Amount`: `input_tokens`, `output_tokens`, `cost`,
+  `tokens`) is the request's output cap and an estimate of its input (images
+  and PDFs counted as such, in attachments and raw content blocks), priced
+  under the model's resolved id. A refusal raises `Smith::BudgetUnavailable`,
+  a `BudgetExceeded`, before anything is sent; a ledger that cannot be built
+  or answer `reserve!` raises `Smith::BudgetLedgerError`; an error from
+  `reconcile!` or `release!` is logged by class and the step goes on. Keys
+  are `"<attempt_id>:<round>"`, and a batch request's `custom_id`: a batch
+  request is held when captured, at the batch discount, and settled when its
+  result comes. Every hold carries `expires_at`,
+  `Smith.config.budget_hold_ttl` (3600 seconds by default) from now, and a
+  batch request's wait longer, so a ledger drops a hold whose process died.
+  `Smith.config.budget_hold_output_tokens` caps a hold's output part (an
+  agent with no `max_tokens` is otherwise held for the model's maximum).
+  A tool loop's later rounds are held only by a step whose `retry_on` names
+  `BudgetUnavailable`: a refused round pauses the loop, its tool calls and
+  results kept with the step's retry (`pending_retry` `continuation`), and
+  the retry continues from them, running none of its tools again; any other
+  step's later rounds go on unheld and are reconciled. A nested workflow
+  without its own ledger charges the enclosing run's; a child run, inline or
+  not, its own class's (readiness warns of a child workflow that declares
+  none, `:child_run_unbudgeted`). Runtime readiness warns of an agent whose
+  model has no price wherever the ledger is charged
+  (`:budget_ledger_unpriced`), and its metrics name the scope keys.
+- Testing kit: `require "smith/testing"` (and `smith/testing/minitest`,
+  `smith/testing/rspec`). `Smith::Testing.stub_agent(agent, outputs:,
+  usage:, stop_reason:, stream:)` answers an agent's requests where they
+  would go over the wire, so the tool loop, budget holds, the response
+  memo, streaming and output checks run as for a provider's reply. Outputs
+  are taken in turn: a String, a Hash as JSON text, or
+  `tool_call(ToolClass, **arguments)`, which runs the agent's own tool (a
+  tool the agent lacks fails the call). Only the stubbed call's own
+  requests are answered, and a batch step's capture and delivery are left
+  to batch mode; `Smith::Testing.unstubbed = :refuse` fails an agent's call
+  that has no stub (`UnstubbedCall`) instead of sending it.
+  `run_until_waiting`, `resume_with` and `expire` drive a
+  run through its waits (a durable retry's backoff ends at once);
+  `batch_result` and `batch_payload` build a batch delivery. Minitest
+  assertions (`assert_waiting_for`, `assert_transitioned_through`,
+  `assert_usage_recorded`) and RSpec matchers (`be_waiting_for`,
+  `have_transitioned_through`, `have_recorded_usage`) drop the stubs after
+  each test.
+- `Smith.config.persistence_max_bytes`: a stored workflow state's bound (nil
+  by default). A stored run's step whose result would take it past the
+  bound fails with `Smith::PersistedStateTooLarge` (a `WorkflowError`,
+  restored as itself) before the result is kept: its usage is recorded, its
+  `on_failure` taken, and the run stays storable, strict mode included. A
+  tool loop refused for budget does not pause into a state past the bound
+  (it goes on unheld). Any other state past it is refused before anything
+  is written, before a split-step boundary counts a write as begun (a
+  refused checkpoint may be made again).
+- `rails g smith:install` also writes a workflow-state migration and model
+  for the `:active_record` adapter (a unique string key, a text payload
+  limited so MySQL picks a type that holds it, a `lock_version`, a
+  payload-size CHECK a third above `persistence_max_bytes`) and configures
+  them; options `--state-model` (a namespaced model gets its table name
+  set), `--max-state-bytes` (a whole number, `0` for no bound) and
+  `--skip-state-model`.
+- `smith doctor` checks an `:active_record` adapter's model on every run
+  (`persistence.state_model`: its `lock_version`, a text payload, a unique
+  string key at least 64 characters wide, through
+  `ActiveRecordStore#check_schema!`), skipping when the database cannot be
+  reached and warning of an encrypted payload, which `replace_exact` now
+  refuses with a clear error (it compares payloads in the database).
+
+### Changed
+
+- The doctor's durability probe writes as runs write (`Workflow#persist!`:
+  `store_versioned` where the adapter has it, and `persistence_max_bytes`),
+  so it now fails where runs would, an `:active_record` adapter with a
+  `persistence_ttl` included.
+
+- Smith's OpenAI Responses path (`openai_api_mode: :auto`) given a streaming
+  block no longer raises `NotImplementedError`: it completes, then passes the
+  block the reply's whole text as one chunk.
+- **Breaking:** workflow context has one shape everywhere.
+  - Top-level keys must be Symbols, the rule `write_context` already applied.
+    `Workflow.new`, and the class-level helpers that derive a persistence key
+    from a context (`restore_or_initialize`, `persisted_state_exists?`,
+    `restorable_billing_state?`, `run_persisted!`), raise
+    `Smith::WorkflowError` naming the first other key. Before, String keys were
+    accepted live and became Symbols only on restore, and a `persistence_key`
+    builder saw the caller's context on the class-level path but the
+    workflow's own on the instance path.
+  - Every Hash key inside a context value becomes the Symbol of its String
+    form, at every depth: in `Workflow.new`, at each `write_context` call (so
+    `read_context` in the same step already sees it), after hooks that write
+    the live context, and on restore. Before, a restore symbolized only
+    top-level keys, so `context.dig(:fields, :title)` returned the value live
+    and `nil` after a JSON round trip. Integer and other keys become Symbols
+    too (`101` becomes `:"101"`, as JSON would make it). Hash subclasses such as
+    `HashWithIndifferentAccess` become plain Hashes, and default procs and
+    `compare_by_identity` are not kept.
+  - Two keys of one Hash that become the same Symbol, a value that contains
+    itself, and nesting deeper than 100 levels (JSON's own limit) raise
+    `Smith::WorkflowError` instead of keeping whichever key came last or
+    overflowing the stack.
+  - Values are not converted: Symbols, Times and other non-JSON values still
+    come back as Strings after a restore.
+  - `Workflow.new` holds a normalized copy, not the caller's Hash.
+  - Normalization is `O(N)` in the entries of the value being normalized.
+- **Breaking:** token totals count prompt-cache input. `RunResult#total_tokens`,
+  the workflow's token totals, token budgets (`total_tokens`, `token_limit`),
+  composite effect totals and `ProviderUsage#total_tokens` add
+  `cache_read_tokens` and `cache_write_tokens` to input and output. Before,
+  cached input was not counted at all, so a workflow that cached heavily stayed
+  far under a token budget it was in fact spending.
+- **Breaking:** `Workflow::AgentResult` gains `cache_read_tokens`,
+  `cache_write_tokens`, `thinking_tokens`, `stop_reason`,
+  `provider_message_id` and `mode` (the last set only by streaming and batch
+  steps), so its `to_h`, `to_a`, `==` and positional deconstruction carry six
+  more members.
+- **Breaking:** `Smith::Pricing.validate_catalog!` refuses catalogs 0.11.0
+  accepted: cache rates that are not non-negative Integers or Floats, a
+  `batch_discount` outside 0 (inclusive) to 1 (exclusive) or not an Integer or
+  Float, and a `batch_discount` inside a tier, where it would never apply.
+- **Breaking:** a tiered pricing entry is chosen on a call's total input
+  (uncached plus cache read plus cache write). Before, it was chosen on
+  uncached input alone, which could select a cheaper tier than the provider
+  bills.
+- **Breaking:** Smith's OpenAI Responses adapter reports `input_tokens` with
+  cached and cache-written input taken out, as RubyLLM reports every other
+  provider, keeping the cache counts separate. Before, its `input_tokens`
+  included cached input, which Smith priced at the full input rate; that input
+  is now priced at `cache_read_cost_per_token`, 0 when the catalog has none, so
+  Responses-path costs fall unless the catalog sets it. Cache counts that are
+  not Integers are ignored, and counts larger than the reported input are
+  capped to it, so the reported input total is kept.
+- **Breaking:** `append_session_messages!` admits only `user`, `assistant`
+  and `tool` messages (see Upgrade notes), and a restored session message or a
+  durable composite step's prepared message must have one of those roles or
+  `system`. Only Smith and the host's `seed_messages` builder put system
+  messages in a session, so the injected-state marker is now recognized only on
+  a system message: a user, assistant or tool message that starts with
+  `[smith:injected-state]` is left alone instead of being replaced or removed
+  as Smith's state.
+- The parallel branch limit check moved into its own graph diagnostic class;
+  its code and output are unchanged.
+- **Breaking:** a workflow's `wall_clock` budget bounds the time its steps
+  spend running, not the time since `created_at`. Each step gets what is left
+  of the budget after the run's persisted `active_seconds`, and adds its own
+  running time when it ends. A step that raised, or whose process died, is
+  charged on the next restore the time since it began (recorded in the
+  checkpoint written before it), at most what is left of the budget. Time spent
+  waiting, or between steps that a host advances from a queue, no longer
+  counts, so a run that used to fail its deadline while idle now continues.
+  Durable composite branches each start from what is left of the budget, and
+  their running time is not added back. Payloads gain `awaiting`,
+  `active_seconds` and `active_step_started_at`; a payload without them
+  restores as not waiting with no active time spent.
+- Rollback: an earlier 0.12 build, and 0.11.0, refuse a persisted failure whose
+  family is `wait_timed_out`, `output_failure` or `child_runs_failed`, and a
+  waiting run whose wait is a map's or call's (`kind: "children"`); clear or
+  settle such runs before rolling back. An earlier build ignores
+  `inherited_untrusted_keys`, so a child run restored there loses its parent's
+  untrusted marks. It refuses a run waiting on a durable retry
+  (`kind: "retry"`) and ignores `pending_retry`, so a run due for a retry
+  would start the step over at its first attempt and key generation; settle
+  such runs first. It cannot load a class that declares `retry_on ...,
+  durable: true` (an unknown keyword), so remove the option first; without it
+  the retry sleeps its backoff, up to `max_delay`, in the worker. It ignores
+  `inherited_artifact_namespaces`, so a child run restored there cannot read
+  its parent's documents, and it sends a seed message with content parts to
+  providers as JSON text.
+- A workflow's execution namespace (the persisted UUID that scopes its
+  artifacts and now its idempotency keys) is assigned when the workflow is
+  built instead of on first artifact use, so `to_state` always carries it,
+  even before the first step. Runs restored from copies of one payload
+  therefore share artifact scope and idempotency keys; build each run with
+  `new`. A payload written without a namespace gets one derived from its
+  class, persistence key and creation time, the same on every restore, and a
+  stored namespace that is not a UUID raises `Smith::SerializationError`.
+- **Breaking:** Smith's per-step tool context (`Smith::Tool::ScopedContext`)
+  holds one more private value, `current_idempotency_scope`.
+  `ScopedContext.around` requires the complete context, so a host that builds
+  that Hash by hand rather than from `ScopedContext.capture` must include it.
+- **Breaking:** an explicit `persist :a, :b` list is an allow-list for the
+  context in every run, persisted or not and nested or not.
+  - `write_context` of any other key raises `Smith::UndeclaredContextKey`
+    (a `WorkflowError`, with `key` and `persisted_keys`). Before, the write
+    took effect in the live run and was dropped at the next checkpoint,
+    contrary to the docs.
+  - A rejected write fails the step even when the step body rescues the
+    error, so it can never become a silently dropped write.
+  - Hooks that receive the live context (`before_eval`, `after_completion`,
+    guardrails) are checked at the end of their step. A new top-level key must
+    be a Symbol the list allows; otherwise the step fails and the context's
+    top-level values go back to how they were when the step started. New or
+    replaced values take the context's key shape.
+  - `persist` refuses keys that are not Symbols with `WorkflowError` at
+    definition time. Before, String keys made every write fail on restore.
+  - `persist :auto` and workflows with no `persist` declaration accept any
+    Symbol key.
+- **Breaking:** restoring a payload whose position the class does not know
+  raises instead of restoring a run that reads as terminal.
+  - An unknown state, or no state while the class has an initial state,
+    raises `Smith::UnknownStateOnRestore` (`workflow`, `persistence_key`,
+    `state`). An undeclared pending transition raises
+    `Smith::UnknownTransitionOnRestore` (`workflow`, `persistence_key`,
+    `transition`). Both are `Smith::Error`s that are neither retryable nor
+    retry-forbidden, with bounded messages.
+  - A state is known when it is declared with `state` or `initial_state`, or
+    named by any transition's `from:` or `to:`. It is matched by its String
+    form (`Workflow.known_state?`, `Workflow.resolve_state_name`, `O(S + T)`),
+    so String-named states restore as the Strings the class declares. Before,
+    a String-named state reached only through transitions restored as an
+    undeclared Symbol and read as terminal.
+  - The check runs after `migrate_from` and after the `definition_digest`
+    check, so a digest mismatch is still reported as one. A migration that
+    maps an old name needs a `persistence_schema_version` bump, since
+    migrations run only when the stored version is behind; the error message
+    says so.
+  - Finished runs whose terminal state was renamed are refused as well, by
+    `restore`, `restore_or_initialize`, `restorable_billing_state?` and the
+    class-level `run_persisted!`. Migrate them, or read the stored JSON
+    directly.
+  - `stuck_for?` reports a stored run in an unknown state as stuck. Before,
+    it reported it as terminal.
+- **Breaking:** a `compute` or `run` step that declares `routes:` must route.
+  - If its target state has an outgoing transition, finishing without
+    `step.route_to` raises `Smith::UnroutedDeterministicStep` (a
+    `WorkflowError`, with `transition` and `routes`), so `on_failure` applies
+    and none of the step's writes are kept. The exceptions are a transition
+    that declares `on_success`, and one that opts into
+    `compute(routes: [...], fallthrough: true)`.
+  - A step whose target state has no outgoing transition may finish unrouted,
+    and the run ends there, so `routes: [:fail]` can still name only an
+    exceptional route.
+  - Before, an unrouted step silently took the first transition declared from
+    its target state.
+  - `fallthrough:` must be `true` or `false`. `fallthrough: true` without
+    `routes:` raises `WorkflowError` at definition time.
+  - Graph inspection follows the runtime rule, so a transition reachable only
+    through the old fall-through is now reported as an `unreachable_transition`
+    warning; declare `fallthrough: true` to keep it.
+  - Transition snapshots of steps with `routes:` carry
+    `deterministic_fallthrough`; other snapshots are unchanged.
+  - A class-less `retry_on` does not retry the new error. `retry_on
+    Smith::WorkflowError` does, until its attempts run out.
+- **Breaking:** nested workflow failures.
+  - A child that raises passes its error to the parent step unchanged,
+    whatever its class, so the parent's `retry_on` and
+    `Smith::Errors.retryable?` see the child's own error at any depth, and the
+    child's billable usage is rolled into the parent on every attempt. Before,
+    a raised `Smith::Error` became a plain non-retryable `WorkflowError`, and
+    the child's usage was not rolled up.
+  - A child that routes its failure through its own `on_failure` has handled
+    it. The parent still fails with a non-retryable `WorkflowError` (`nested
+    workflow failed: ...`, now bounded to 1 KiB), exactly as before.
+- **Breaking:** tool evidence travels up through nesting. A step that runs
+  inside another step's execution (a nested workflow's step) marks the
+  enclosing step's tool execution tracker when a tool ran in it. So when a
+  tool ran in any child step, a failure of the parent step becomes
+  `Smith::ToolOutcomeUncertain` and is never retried, exactly as when the tool
+  runs in the parent step itself. Before, a parent could retry a child whose
+  tools had already run.
+- **Breaking:** `retry_on` starts no attempt once the workflow's effective
+  wall-clock deadline has passed. Before, a step that hit its deadline could
+  sleep through every backoff and fail again each time.
+- **Breaking:** `:deterministic_step` traces report `outcome` (`:started`,
+  `:success`, `:routed`, `:failed`) instead of `result`. `result` is a
+  reserved content key that the default content policy strips, and `outcome`
+  matches the `:transition` and `:provider_call` vocabulary. A failure carries
+  `error_class`, `error_family`, and `retryable` when known, instead of the
+  raw exception message, which could hold content. Hosts that read `result` or
+  `error` from these traces, or that name them in a `trace_fields` allowlist
+  for `:deterministic_step`, must switch to `outcome` and `error_class`;
+  otherwise they receive neither.
+- **Breaking:** `trace_content :redacted` masks content only, and masks it
+  completely.
+  - The built-in Memory, Logger and OpenTelemetry adapters mask the content
+    fields `content`, `prompt`, `response`, `args`, and `result`, and leave
+    every other field readable. That includes identifiers such as `model`,
+    `tool`, `attempt_id`, `error_class`, and `execution_key`, which defaults
+    to the persistence key and may embed host identifiers. Before, they
+    masked every String value.
+  - Masking is recursive, in the central policy too (`args` and `result`):
+    every String and Symbol at any depth of Hashes and Arrays becomes
+    `"[REDACTED]"`, so nested content no longer leaks. Numbers, booleans and
+    nil are kept.
+  - Hosts that relied on `:redacted` to hide identifiers, or fields a custom
+    trace adds, must drop them with `trace_fields`.
+
+### Fixed
+
+- A step's failed attempts no longer outlive it on its thread. Smith added
+  them to the thread's list in place, and the step's thread context put that
+  same list back when the step ended, so a thread that had made a call outside
+  any step carried one step's failed attempts into the next step's budget
+  settlement (counted twice, possibly in another run).
+- Budgets settle every billed token. The completed rounds of a tool loop whose
+  attempt then failed, and the metered responses of a tool loop in which some
+  response reported no usage, were recorded in usage entries and run totals but
+  never reached the budget ledger. A failed attempt's own reported cache tokens
+  were in its `:provider_call` trace but not in its usage entry, cost, totals or
+  budget. Budgets may now be reached sooner than in 0.11.0.
+- Flat pricing entries with String keys (`"input_cost_per_token"`), as a
+  catalog loaded from JSON or YAML has, are priced. They were silently
+  unpriced, while tiered entries already read String keys; `total_cost` budgets
+  that never consumed such calls now do.
+- `docs/CONFIGURATION.md` said a provider-qualified call with only a
+  model-only rate raises `Smith::PricingConfigurationError`; `compute_cost`
+  never raises and leaves such usage unpriced. The docs, the README example and
+  the generator's pricing example now use provider-qualified keys through
+  `Smith::Pricing.validate_catalog!`.
+- A failure whose `details` raises an error whose own `message` also raises no
+  longer replaces the step's error (`FailureRecord` reads that inner message
+  through its guarded reader). This was present in 0.11.0.
+- Classifying a deterministic step's failure for its trace can never replace
+  the step's error, and is skipped when no trace adapter is configured.
+- The `compute` example in `docs/PATTERNS.md` called `route_to` twice on one
+  path, which raises. It now routes once on each branch and declares its
+  routes.
+
 ## [0.11.0] - 2026-10-07
 
 ### Added