smith-agents 0.7.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 450ce06c1d96f41a8b6ae6d0c0dd1b8dcc88b58d3da786d8536a26ecc8f111bb
-  data.tar.gz: 7b0696ff9aaccc3016ebef5223c4ded71aeeb883d1a1b70e6f2ab5959657e1da
+  metadata.gz: 06665b52b660baf1f846ebd104caec677044595bd4aaf71ecf6ac3120e18d478
+  data.tar.gz: '09dd67e047e0f2a3dc6afd0f6b320ab7d5b7f2f23460ddae9576860e7b2e1329'
 SHA512:
-  metadata.gz: da3c5cb55ef7efac304f223eb7ce468f058b4d85c9c4b60ea102f50882789d067eaf9c2a212871eb66a215f7f1cce2baa29de945dd3c0f2c0cc084d187fec1ae
-  data.tar.gz: 910ec83bc644cdbb5ad1a737ef1aa95af3d5ca784d952fea9179ae4b7e44d49a1edf7a7ae2b067c7a83a227bb623d3d6c798cc45a8d254501ff397f99e876b69
+  metadata.gz: 76771bcb4d58d45f110b16a590579a34f698f1e9e2b75cca7806a5c5864f50c8209afc4a258a587069c6dd97f6ae87c1d0a62d434afd4b415f04e199561e79a6
+  data.tar.gz: 5160511ae311634881c774fa8040d3b69f93171e20e76aca595821c9eb7a767c76d0165ffe562190b16f624a4ba2e3e272822b3a1cf6b852ae2d2af7d7521994

data/CHANGELOG.md

@@ -4,6 +4,462 @@ 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.10.0] - 2026-08-24
+
+### Added
+
+- Last-serial-agent-execution attribution. A deterministic (`compute`) step can
+  now read the model and provider that actually served the most recent serial
+  `execute :agent` step via `DeterministicStep#last_agent_model` /
+  `#last_agent_provider` (symmetric with `#last_output`, which returns that
+  step's content). The value is the resolved model/provider after fallback
+  resolution, so a step that failed its primary and completed on a
+  `fallback_models` entry reports the model that actually ran, never the
+  configured primary. It is durable lifecycle state (persisted in `to_state` as
+  `last_agent_execution`, restored across crash/resume), not a trace scrape, and
+  is `nil` until a serial agent step runs. Backward compatible: pre-upgrade
+  states have no `last_agent_execution` key and restore to `nil`; old readers
+  slice off the unknown key.
+
+### Fixed
+
+- Structured agent outputs recorded as session messages (Hash or Array
+  content) are now serialized to JSON at the RubyLLM provider boundary when
+  replayed to a later agent step. RubyLLM treats a Hash message content as
+  attachments and opens each value as a file, so replaying a prior structured
+  output to the next agent in a workflow session raised `Errno::ENOENT`. The
+  session store is unaffected: `last_output` and persisted `session_messages`
+  keep the raw structured value; only the provider-facing copy is serialized.
+
+## [0.9.0] - 2026-08-03
+
+### Upgrade notes
+
+- Rollback after running fan-out branches under this version is a one-way
+  door for those runs: composite branch effects written with attribution
+  values (usage entries) or batch-correlated `tool_call_id` capture entries
+  fail an older gem's exact-key validation at reduction or recovery.
+  Drain in-flight composite runs before rolling the gem back; plain
+  checkpoint payloads are unaffected (restored pre-attribution documents
+  re-serialize byte-identically, and old readers slice off unknown keys).
+- Hosts with a configured trace adapter see new output on upgrade without
+  any host change: one `:provider_call` line per provider attempt, one
+  `:cost` line per priced completed invocation, failed `:transition` lines
+  marked `outcome: :failed`, and ambient attribution keys (including
+  `execution_key`, the Smith persistence key) merged into every payload.
+  Identifier-only, but plan for the volume and shape change, especially
+  with `Smith::Trace::Logger` in production.
+- Hosts with a `trace_fields` allowlist for `:transition` must add
+  `:outcome` (and the error keys they want) or failed transitions render
+  indistinguishable from successes under the allowlist.
+- `Smith::Trace::Memory` is now bounded (default 10,000 entries, silent
+  drop with `dropped_count`); previously it accumulated without limit.
+
+### Added
+
+- Add `Smith::Attribution`, an immutable thread-local execution attribution
+  context (`execution_key`, `transition`, `from`, `to`, `branch_key`,
+  `round`). Workflow execution installs it per step (the `execution_key`
+  defaults to the persistence key of a persisted run), fan-out carries it
+  into branch threads and overlays the branch key, and evaluator-optimizer
+  rounds overlay the round index. Hosts can seed an outer scope with
+  `Smith::Attribution.with(execution_key: ...)` around non-persisted runs.
+  Restoration inside workflow execution rides `ThreadContextSnapshot`, which
+  now tracks the attribution thread key. Scope overlays are nil-ignoring
+  (`Context#merge`), but the per-step facts (`transition`, `from`, `to`)
+  are replaced verbatim, nil included (`Context#override`): a nested
+  child's `from`-less transition never inherits the parent step's `from`,
+  and the failed `:transition` trace keeps `from`/`to` present even when
+  nil for the same reason.
+- Merge ambient attribution fields into every `Smith::Trace.record` payload.
+  Attribution keys are identifiers, not content: caller-supplied keys win on
+  conflict, the content policy is unaffected, and a configured
+  `trace_fields` allowlist stays authoritative (add attribution keys to an
+  allowlist to receive them). Disable with `Smith.config.trace_attribution =
+  false` (default true).
+- Bound `Smith::Trace::Memory` (default 10,000 entries) with a
+  `dropped_count` reader and a `snapshot` method for readers racing
+  concurrent recording.
+- Tag `Workflow::UsageEntry` with the ambient attribution at recording time:
+  new optional members `transition`, `branch_key`, `round`, and `attempt_id`.
+  All four are nil on entries restored from checkpoints written by earlier
+  Smith versions and are omitted from serialization when nil, so restored
+  pre-attribution documents re-serialize byte-identically (hosts that digest
+  whole persisted documents in exact-mutation proofs depend on this). A
+  rolled-back gem drops the new keys from plain checkpoint payloads
+  (`from_h` slices to known members). Composite branch effects are the
+  exception: effects written by this version from a fan-out branch carry
+  real attribution values, and an older gem's exact-key effects validation
+  rejects them, so see the upgrade notes below before rolling back.
+  `recorded_at` now carries microsecond precision (`iso8601(6)`) on new
+  entries. Recording symbolizes `transition`/`branch_key` Strings exactly
+  as `from_h` does on restore, so a host seeding String attribution through
+  `Smith::Attribution.with` gets entries equal to their restored form.
+- Measure each provider attempt with a monotonic clock around the whole chat
+  completion (including any provider tool loop) and emit one
+  `:provider_call` trace per attempt (success or failure) carrying `model`,
+  `provider`, `duration_ms`, `attempt_id`, `attempt_index`, and `outcome`.
+  Every usage entry the attempt produced shares its `attempt_id` (an attempt
+  with an N-round tool loop records N entries): join there for the attempt's
+  single duration, never sum across entries. Gate with
+  `Smith.config.trace_provider_calls` (default true). `ProviderAttempt`
+  gains optional `attempt_id` and `duration_ms`.
+- Add a public read-only `Workflow#usage_entries` (frozen copy under the
+  recording mutex) so hosts can diff usage across a step boundary without a
+  full `to_state` serialization; `to_state` and `snapshot_usage_entries` now
+  read the ledger under the same mutex, so a state written mid-fan-out never
+  captures a torn array.
+- Thread real correlation identity through events: `Smith::Event#execution_id`
+  and `#trace_id` default to the ambient attribution execution key (the
+  persistence key during persisted runs) instead of a fresh random UUID per
+  event; the random fallback remains for events built outside any execution
+  scope. The `:tool_call` trace gains a nullable `tool_call_id` when the
+  invocation came from a provider batch (the tool-results capture entry
+  gains the same key under a later bullet in this release; composite
+  effects accept the extended shape with bounded value validation).
+
+- Emit from the step-failure paths, closing the success-only observation
+  gap: both `handle_step_failure` and the unresolved-transition handler now
+  record a `:transition` trace with `outcome: :failed` plus bounded
+  classification (`error_class`, `error_family` from FailureRecord's
+  taxonomy, `retryable`) and emit a new `Smith::Events::StepFailed` event.
+  Raw error messages never ride either; an emission failure is logged and
+  can never mask the original step error. The marker key is `outcome`
+  because `result` is a reserved content key in the trace pipeline. An
+  unresolved transition with no `:fail` transition still re-raises without
+  emitting: that path was never treated as a step. The unresolved handler
+  runs outside any step context, so it seeds the run identity explicitly;
+  both failure paths stamp persisted-run events with the persistence key.
+  Emission is terminal-per-step: a step that retries internally and then
+  succeeds emits only its `StepCompleted`; intermediate step-body retry
+  attempts stay dark at the step layer (provider-level failures remain
+  visible as `:provider_call` failure traces). `StepFailed` handlers run
+  outside the step snapshot's interrupt-masked region (emission is staged
+  in the failure rescue and flushed after the mask closes), interruptible
+  exactly like `StepCompleted` handlers. A step body that surfaces Smith's
+  own `UnresolvedTransitionError` emits exactly one `StepFailed` under the
+  real step identity; the unresolved handler recognizes the already-emitted
+  error instead of emitting a second event under the requested (never
+  executed) name.
+- Emit the long-advertised `:cost` trace: one per completed agent
+  invocation, whose value is the sum of that invocation's per-response
+  usage-entry costs. Summing per response is what tiered catalogs actually
+  bill; pricing the aggregate token totals as one call would resolve the
+  wrong tier for multi-response tool loops. Emitted only for fully metered,
+  fully priced invocations (a partially priced or partially metered
+  invocation emits nothing rather than presenting an incomplete figure);
+  gated by the existing `trace_cost` setting (the per-type gates live in
+  the built-in adapters; a custom adapter receives every type). `:cost`
+  traces are not a spend total: billed failed and partial attempts appear
+  only in usage entries. The same per-response sum now becomes
+  `agent_result.cost`, so budget settlement, result surfaces, recorded
+  entries, and the trace all agree on one invocation cost.
+- The OpenTelemetry adapter now creates retroactive spans with real
+  durations (span start backdated by `:tool_call` seconds or
+  `:provider_call` milliseconds; instant spans otherwise), preserves
+  numeric attribute types instead of stringifying everything, and uses only
+  the documented opentelemetry-api surface (`Tracer#start_span` with
+  `start_timestamp`, `Span#finish` with `end_timestamp`).
+
+- Add a `workflow` discriminator to the ambient attribution, every trace
+  payload, usage entries, and the `StepCompleted`/`StepFailed` events: the
+  emitting workflow's class name ("anonymous" when unnamed), so
+  nested-child graph facts are distinguishable from parent facts under the
+  shared root execution identity. Nil-omitted from serialized entries like
+  the other attribution members.
+- Every provider attempt now emits its `:provider_call` trace: `outcome` is
+  `:success`, `:failure` (provider failure, fallback may continue), or
+  `:aborted` (a non-provider error that re-raises), so prefix-accounted
+  usage entries always have their attempt join target.
+- The tool-results capture entry gains `tool_call_id` when the invocation
+  came from a provider batch (omitted otherwise, so direct-invocation and
+  pre-existing payloads keep their exact two-key shape); composite effects
+  accept the extended shape while still rejecting unknown keys.
+- `StepFailed` handlers now run outside the step snapshot's
+  interrupt-masked region: emission is staged in the failure rescue and
+  flushed after the mask closes with explicitly seeded run identity, so a
+  slow host handler can no longer make the workflow thread unkillable and
+  handlers match `StepCompleted`'s interruptibility.
+
+### Fixed
+
+- A user-declared `:fail` transition no longer inherits the early order
+  position of the auto-generated placeholder created by `state :failed`:
+  redeclaring a generated transition takes a fresh declaration position, so
+  it can no longer shadow a same-origin primary transition at run time.
+  Genuine user redefinitions keep their original position, and subclasses
+  inherit the bookkeeping.
+- Budget cost settlement now consumes the per-response priced sum instead
+  of pricing the invocation's aggregate token totals. Under linear pricing
+  the figures are identical; under tiered pricing the aggregate resolved
+  the wrong tier (or missed every tier and settled zero), so a
+  cost-budgeted workflow could keep spending after its real billed cost
+  exceeded the budget.
+
+### Removed
+
+- Remove the never-read `trace_retention` and `trace_tenant_isolation`
+  settings. Both were silent no-ops since introduction; reading or writing
+  them now raises, so a host relying on the illusion fails loudly instead
+  of silently.
+
+### Changed
+
+- Workflow step failure is now observable: subscribers to the events bus
+  receive `StepFailed` where previously failures emitted nothing (the
+  success-only scope is gone), and trace consumers see failed `:transition`
+  payloads distinguished by `outcome: :failed`.
+- `Workflow::Composite::Effects` validates usage-entry keys as
+  required-plus-allowed instead of exact: entries from an older producer
+  (missing the optional attribution keys) stay valid, current entries with
+  attribution pass, and unknown keys still reject. The optional keys are
+  bounded values, not just bounded keys: `transition`, `branch_key`, and
+  `workflow` must be non-empty Strings up to 256 characters, `round` a
+  non-negative Integer, and `attempt_id` a UUID when present. Tool results
+  accept the extended capture shape: `tool_call_id`, when present, must be
+  a non-empty String up to 1024 characters (`tool` keeps its exact prior
+  validation).
+
+
+- `Smith::Events` subscriptions now live in per-class buckets guarded by a
+  mutex: emit touches only the buckets for the event's ancestors instead of
+  scanning every subscription, dispatch order remains registration order,
+  and `is_a?` matching semantics are unchanged (instance-extended modules
+  dispatch through the singleton class; immediate values, which have no
+  singleton class and cannot be extended, dispatch through their class
+  ancestors). `Subscription#cancel` now
+  detaches from the registry, so cancelled subscriptions (including
+  `Events.within` scopes) no longer leak. Handlers run outside the registry
+  lock, so a handler may subscribe or cancel without deadlocking.
+- `Smith::Trace::Memory#record` and `#clear!` are mutex-guarded and safe
+  under parallel fan-out branches.
+
+## [0.8.0] - 2026-07-25
+
+### Added
+
+- Add opt-in graceful agent tool-budget exhaustion with a finite
+  `tool_calls` budget and `tool_budget_exhaustion :complete`. Smith consumes
+  model-requested calls atomically, rejects oversized batches without partial
+  execution, pairs every rejected call id, and performs one tool-disabled final
+  completion.
+- Add one-use call admissions so an admitted Smith tool is not double charged,
+  while exact tool identity prevents nested tools from stealing an admission.
+- Aggregate trustworthy token usage across every assistant response in a
+  successful RubyLLM tool loop, record one durable usage entry per provider
+  response, and preserve completed-prefix usage when a later provider round
+  fails.
+- Expose immutable normalized tool-call metadata and one execution-scoped,
+  host-seedable invocation sequence across Smith-managed chats, branches,
+  threads, and fibers without introducing host persistence semantics.
+- Add immutable exact tool-call budgets with aggregate and per-tool limits for
+  host-controlled execution scopes.
+- Add a host-neutral whole-batch admission callback and per-invocation dispatch
+  failure callback. Smith snapshots immutable requests, admits the complete
+  Smith-managed subset of the provider batch before dispatch, and never reports
+  failure for a batch whose host admission callback raised.
+- Add a Claude 5+ family inference rule: Fable, Mythos, Opus, Sonnet, and Haiku
+  ids with major version 5 or higher resolve to adaptive thinking, no
+  temperature accepted, and native tools-with-thinking, so an agent-declared
+  `temperature` is stripped instead of being sent to a provider that rejects
+  it. Dotted 4.x ids (for example `claude-haiku-4-5`) keep matching the 4.x
+  budget-tokens rule.
+- Add new public error classes hosts may rescue or allowlist:
+  `Smith::PricingConfigurationError`, `Smith::ProviderPermanentFailure`
+  (carries `provider`, `model_id`, and `source_error_class`),
+  `Smith::Models::AmbiguousProfileError`, `Smith::Models::CollisionError`,
+  `Smith::ToolDispatchRejected`, `Smith::ToolOutcomeUncertain`,
+  `Smith::ToolExecutionNotAdmitted`, `Smith::ToolFailureNotificationFailed`,
+  `Smith::BoundedCompletionError`, and `Smith::PersistedFailureInvalid`.
+  Terminal tool-evidence families surface through
+  `Smith::Errors.retry_forbidden?` / `retry_forbidden_class?` and must never be
+  retried by host jobs.
+- `Smith::Doctor` reports a dedicated failing `models.ambiguity` check when a
+  registered agent declares an unqualified model id registered under multiple
+  providers, instead of aborting the run with `AmbiguousProfileError`, and now
+  validates the assigned pricing catalog (legacy model-only keys, malformed
+  entries, and colliding keys fail the `config.pricing` check).
+- Capture the causal failure classification behind an uncertain tool outcome
+  into the durable failure record: a persisted `Smith::ToolOutcomeUncertain`
+  carries bounded `error_cause_class`, `error_cause_family`, and
+  `error_cause_message` from its cause so a restored host can distinguish a
+  deadline, cancellation, or defect. The three attributes travel as one unit;
+  legacy records omit all three, and a partial or unknown-family set fails
+  closed at state admission.
+
+### Changed
+
+- Bump `Smith::EXECUTION_SEMANTICS_VERSION` from `3` directly to `5` for exact
+  per-tool budgets, shared composite admission, bounded graceful completion,
+  and cumulative tool-loop usage. The value `4` was consumed transiently during
+  development of this slice and is intentionally skipped so a composite plan
+  persisted against an interim build can never read as compatible with the
+  released semantics; consumers compare by exact equality, so every pre-`5`
+  plan is invalidated either way.
+- Key model profiles, fallback candidates, usage telemetry, and pricing by exact
+  provider/model identity. Provider-qualified pricing never falls back to a
+  legacy model-only rate, and fallback declarations must name their provider.
+- Let observation masking preserve the exact immutable seed-message prefix
+  while bounding only later workflow observations. The prefix length is
+  persisted and validated across restart; legacy state defaults to zero.
+- Require the exactly qualified RubyLLM `1.16.0`; graceful completion is
+  isolated behind that verified chat interface and fails closed on incompatible
+  hooks. Future RubyLLM versions require an explicit compatibility pass.
+- Enforce the pricing-catalog key policy at admission time instead of inside
+  accounting: `Smith::Pricing.validate_catalog!` rejects legacy model-only
+  keys, unrecognized key shapes, malformed entries, and post-normalization
+  collisions, and the doctor runs it against the assigned catalog.
+  `Pricing.compute_cost` itself never raises: a provider-qualified lookup reads
+  only provider-qualified entries and returns nil (visibly unpriced) when only
+  a legacy rate exists, so an in-flight accounting path can never mask a
+  provider error with a pricing configuration error.
+- Registering a model profile whose capabilities differ from the profile
+  already registered for the same provider/model identity now raises
+  `Smith::Models::CollisionError`; earlier releases silently replaced the
+  profile on Rails reload. Re-registering a value-identical profile stays
+  idempotent (see Migration notes).
+- `Smith::Models::Normalizer` tool/endpoint routing no longer requires active
+  thinking: endpoint compatibility is evaluated on every chat construction, the
+  endpoint preserving the strictly larger compatible tool subset wins (ties
+  keep the current endpoint; a single forced tool that only one endpoint can
+  carry takes precedence), and each dropped tool records a `:tool_dropped`
+  decision. See docs/TOOLS_AND_GUARDRAILS.md.
+- Agent tool evidence is tracked per transition: once any tool starts inside a
+  transition, a later provider failure in that transition (including one from a
+  concurrently executing parallel branch that never ran a tool itself) refuses
+  model fallback and surfaces `Smith::ToolOutcomeUncertain`. This is
+  deliberately conservative and fail-closed; branch-scoped evidence that
+  restores fallback for provably tool-free sibling branches is planned, and
+  child-workflow tool evidence does not yet mark the parent transition.
+- `from_state` failure-record problems raise `Smith::PersistedFailureInvalid`
+  while other persisted-shape problems keep raising
+  `Smith::SerializationError`; both descend from `Smith::Error`, and hosts
+  rescuing `SerializationError` around restore must handle both.
+- Restored failure records no longer resolve or construct arbitrary error
+  classes named by persisted data: host-defined subclasses reconstruct as their
+  Smith family parent (family `"other"` restores as `RuntimeError`), so
+  exact-class matching against restored `last_error` values must move to family
+  or `is_a?` checks.
+- `Smith::Agent.fallback_models` now returns a frozen array of
+  `Smith::Agent::ModelReference` values (previously raw strings), block-form
+  `model {}` declarations must return a provider-qualified reference (a bare
+  string raises `Smith::AgentError`), permanent provider failures raise
+  `Smith::ProviderPermanentFailure` instead of a retryable `AgentError`,
+  non-provider `StandardError`s raised inside a provider attempt now propagate
+  raw instead of being wrapped, and `Workflow::UsageEntry` is frozen and gained
+  a `:provider` member.
+
+### Fixed
+
+- Preserve the provider and model actually selected by RubyLLM in completion
+  usage, keep inherited fallback configuration immutable, and treat model-level
+  permission failures as model scoped so an eligible fallback on the same
+  provider remains available. Only account-wide authentication and payment
+  failures suppress later candidates from that provider.
+- Prevent unavailable provider tool calls from creating an unbounded correction
+  loop by consuming the model-request allowance before dispatch.
+- Prevent fallback-model restart after a Smith tool begins executing, because a
+  fresh chat would discard tool evidence and violate the provider protocol.
+- Prevent transition retry, including broad explicit retry classes, when any
+  later provider, completion hook, output validation, or guardrail failure occurs
+  after a bound tool dispatch makes the external outcome uncertain.
+- Reserve provider batches atomically against both the agent allowance and the
+  effective workflow tool budget, then reconcile unexecuted calls.
+- Execute bounded tool loops iteratively so finite call allowances do not grow
+  Ruby stack depth, reject concurrent or callback reentry on one bounded chat,
+  and retain RubyLLM's native forced-tool-choice reset.
+- Validate `Smith::Tool#perform` keyword arguments before budget charge and tool
+  execution, reject non-Smith bindings from the opt-in bounded policy, and fail
+  closed when raw provider params try to override reserved tool controls.
+- Keep provider-facing tool controls and RubyLLM instrumentation aligned, and
+  restore tools, call preferences, and concurrency after success or failure.
+- Permit bounded providers to return multiple calls in one response while more
+  than one call remains. Smith retains atomic batch reservation, deterministic
+  sequential execution, and fail-closed oversized-batch handling.
+- Propagate one enclosing tool-call allowance into same-agent parallel and
+  heterogeneous fan-out worker threads so branches cannot multiply a host's
+  signed transition budget.
+- Materialize one immutable admitted dispatch batch before host admission, so
+  later mutation of the provider collection, call identity, or arguments cannot
+  alter which Smith tools execute or the values they receive. The host callback
+  receives immutable source-call evidence while RubyLLM dispatches a separately
+  owned admitted call, and an atomic dispatch claim prevents callback re-entry
+  from executing the same admission twice. Continue to reject registered-tool
+  replacement and classify only guaranteed pre-`perform` failures as
+  `ToolDispatchRejected`.
+- Capture provider batches with native `Hash` operations, bound the complete
+  provider batch to 100 calls and 1 MiB of UTF-8 call metadata, reject malformed
+  call protocol before host admission, and stop aggregate metadata capture as
+  soon as the bound is crossed.
+- Bound immutable argument copying before child allocation, account for expanded
+  serialized occurrences even when a caller reuses a shared object graph,
+  admit each mutable container's native size before one shallow copy, verify the
+  copy retained that size before child allocation, reject hostile container
+  overrides and malformed UTF-8, and keep traversal iterative with linear time
+  and bounded space.
+- Require one exact execution authority for every managed Smith tool dispatch.
+  Direct tool calls from provider callbacks and nested Smith tool calls now fail
+  closed; nested execution requires a future separately admitted primitive.
+- Give terminal tool-evidence failures precedence during parallel arbitration
+  and centralize their non-retryable classification across declaration and
+  execution. Persist and restore terminal notification failures without resolving
+  or constructing arbitrary classes named by persisted data. Bound and normalize
+  failure diagnostics, capture failure class identity with native Ruby operations,
+  and reject inconsistent family/retry metadata or malformed typed failure details
+  at state admission.
+- Cover the split execution files with direct-load contracts so each new file
+  loads standalone; the released artifact's file manifest is verified against
+  `lib/` at release time as part of the release procedure.
+- Fail closed with a typed `Smith::AgentError` when an agent has no executable
+  model candidate (empty model chain), instead of leaking the exhausted
+  candidate sequence into nil destructuring from optimizer and orchestrator
+  paths.
+- Attribute an account-wide authentication or payment failure to the attempted
+  reference's declared provider when the chat is unobservable, so a dead
+  provider account is not billed a second same-provider attempt.
+- Deduplicate model candidates by physical identity, so a provider-unqualified
+  primary and a provider-qualified fallback naming the same model cannot
+  produce a duplicate attempt, and `ModelReference.coerce` now parses the
+  `"provider/model"` string form that `#to_s` emits (the first slash splits, so
+  slashed model ids round-trip).
+- Keep captured and restored failure records symmetric for blank messages:
+  capture substitutes a deterministic placeholder for a blank error message, so
+  a workflow state whose last failed step had an empty message restores instead
+  of raising `Smith::PersistedFailureInvalid` and poisoning crash/resume.
+- Restore legacy failure records whose `error_message` exceeds the 64 KiB
+  diagnostic bound by truncating exactly as capture truncates, instead of
+  rejecting the persisted workflow state for message length alone; non-text and
+  invalid-UTF-8 persisted values still fail closed.
+- Scope an agent `tool_calls` budget under a legacy Hash tool-call allowance to
+  a typed rejection at both call sites instead of an untyped `NoMethodError`
+  mid-transition.
+- Propagate a settled or exhausted batch reservation's refusal through
+  `CallAdmission#claim`, so a post-settlement execution can never run against
+  an already reconciled ledger.
+- Keep a queued process-fatal sibling error ahead of a
+  `ToolFailureNotificationFailed` raised while notifying unsettled batch
+  failures, so notification problems cannot mask fatal arbitration outcomes.
+
+### Migration notes
+
+- Pricing catalogs must move to provider-qualified keys (`%w[provider model]`
+  arrays or `"provider/model"` strings). Legacy model-only keys still price
+  provider-unqualified usage for compatibility, but they fail
+  `Smith::Pricing.validate_catalog!` (now run by the doctor), and
+  provider-qualified usage never reads them: such usage records nil cost until
+  the catalog is qualified.
+- `fallback_models` entries must name their provider (`"provider/model"`, a
+  Hash, or a `ModelReference`); bare model ids fail closed at class definition.
+- Hosts registering `Smith::Models` profiles from reloadable code must move
+  registration to boot-once initializers or restart after editing a profile;
+  value-different re-registration now raises `Smith::Models::CollisionError`.
+- The gem now requires exactly `ruby_llm 1.16.0` (previously `>= 1.15,
+  < 1.17`); hosts on 1.15.x must upgrade together with this release.
+- Hosts that rescued `Smith::AgentError` for permanent provider failures should
+  rescue `Smith::ProviderPermanentFailure`, and restore-time rescues of
+  `Smith::SerializationError` must also handle
+  `Smith::PersistedFailureInvalid`.
+
 ## [0.7.0] - 2026-07-21
 
 ### Added

data/README.md

@@ -366,9 +366,41 @@ class SearchAgent < Smith::Agent
   register_as :search_agent
   model "claude-opus-4-7"
   tools Smith::Tools::WebSearch, Smith::Tools::UrlFetcher
+  budget tool_calls: 3
+  tool_budget_exhaustion :complete
 end
 ```
 
+Agent tool-call budgets default to raising `Smith::BudgetExceeded` when a tool
+tries to execute beyond the configured limit. Agents that declare
+`tool_budget_exhaustion :complete` must also declare a finite `tool_calls`
+budget. Smith then consumes each model-requested call before dispatch, executes
+only a complete batch admitted against both agent and workflow limits, and
+performs one tool-disabled completion when the allowance is exhausted or the
+provider returns an oversized batch. The bounded provider loop is iterative,
+not recursive. Calls to unavailable tools consume allowance as well, so a
+provider cannot create an unbounded correction loop. Workflow reservations are
+reconciled to actual Smith tool execution.
+
+Hosts may install `Smith::Tool::CallBudget` with exact per-tool limits through
+`Smith::Tool.with_call_budget`. Smith propagates that same root allowance into
+parallel and heterogeneous fan-out worker threads; agent budgets narrow the
+root and all branches share its atomic counters.
+
+Graceful exhaustion is an in-process protocol guarantee, not durable recovery
+for the model/tool loop. If the process exits after a tool begins and before the
+agent completes, the host must treat the outcome as uncertain unless it owns a
+durable per-invocation receipt and reconciliation contract. Smith also refuses
+to start a fresh fallback-model chat after tool execution has begun because that
+would discard the captured evidence and conversation protocol.
+
+Within a host invocation scope, `Smith::Tool.current_invocation` exposes the
+normalized tool-call ID and deterministic execution/batch ordinals. The ID is
+RubyLLM correlation metadata and must not be treated as a provider idempotency
+key. Durable hosts can pass an explicitly seeded
+`Smith::Tool::InvocationSequence` to `with_invocation_context`; Smith itself does
+not persist or reconcile operation receipts.
+
 Guardrails run as input/output gates around agent calls. See [`docs/TOOLS_AND_GUARDRAILS.md`](docs/TOOLS_AND_GUARDRAILS.md).
 
 ## Budgets and Deadlines
@@ -434,7 +466,25 @@ Smith ships a per-attempt normalizer that translates the request payload to what
 - OpenAI gpt-5 family reasoning_effort with `/v1/responses` routing when tools + thinking are combined
 - Gemini 2.5+ budget_tokens
 
-Override the inferred profile per-app via `Smith::Models.register(Profile.new(...))`. Hosts pin to specific model_ids by registering profiles; Smith never hardcodes model_ids in the library.
+Override the inferred profile per-app via `Smith::Models.register(Profile.new(...))`.
+Profiles are keyed by both provider and model id. Pass `provider:` to
+`Smith::Models.find` or `find_or_infer` whenever an id exists under more than
+one provider; an ambiguous unqualified lookup fails closed. Smith never
+hardcodes model ids in the library.
+
+Provider-qualified fallback entries use the same exact identity:
+
+```ruby
+fallback_models(
+  { model: "claude-sonnet-4-6", provider: :anthropic },
+  { model: "openai/gpt-5", provider: :openrouter }
+)
+```
+
+Fallback entries must include an explicit provider. Smith does not infer a
+fallback provider from the primary model or from a model id because the same id
+may be registered by more than one provider. Unqualified fallback entries fail
+closed during agent configuration.
 
 ## Errors and retry
 
@@ -446,6 +496,9 @@ Smith::Errors.retryable?(error)
 
 Smith::Errors.retryable_classes
 # => [Smith::AgentError, Smith::DeadlineExceeded]  (for ActiveJob retry_on)
+
+Smith::Errors.retry_forbidden?(error)
+# => true for terminal tool-evidence failures that must never be replayed
 ```
 
 Workflow transitions can also declare a bounded local retry policy:
@@ -465,6 +518,23 @@ and external idempotency guarantees remain host-owned.
 
 - Executable graph reachability is iterative `O(V + E)` time and `O(V)` space,
   using indexed outgoing transitions and runtime-equivalent successor rules.
+- Smith-managed tool arguments are copied iteratively in `O(N + B)` time and
+  `O(N + B)` bounded space for `N` expanded JSON value occurrences and `B`
+  expanded encoded bytes. Reused subgraphs are charged for every serialized
+  occurrence, native `Array` and `Hash` operations bypass hostile overrides, and
+  every mutable container's native size is admitted before one shallow copy is
+  made. Smith verifies the copy retained the admitted size before allocating or
+  traversing children. One immutable dispatch collection remains authoritative
+  from host admission through RubyLLM execution. The complete provider batch is
+  bounded to 100 calls and 1 MiB of normalized UTF-8 call metadata. The capture
+  boundary transfers temporary ownership of the provider collection and argument
+  graph to Smith: callers must not mutate them concurrently. Smith detects changed
+  cardinality and fails closed, but Ruby cannot prevent an unrelated writer from
+  growing a caller-owned container between native size admission and the native
+  copy without freezing that caller-owned object.
+- Admitted tool-receipt settlement scans each batch once in `O(B)` time and
+  `O(B)` state for `B` admitted Smith calls, including when an earlier terminal
+  callback fails.
 - Parallel execution is `O(B)` scheduling and result space for `B` branches,
   with at most `C = parallel_concurrency` active worker threads per top-level
   execution. Re-entrant fan-out inherits the same cancellation signal and uses

data/docs/CONFIGURATION.md

@@ -49,6 +49,21 @@ Use workflow classes for orchestration behavior:
 - "How much total budget can the whole workflow consume?" -> workflow budget
 - "Which provider credentials should the app use?" -> RubyLLM, not Smith
 
+### Provider-qualified fallback models
+
+Fallback models are exact model/provider identities:
+
+```ruby
+fallback_models(
+  { model: "claude-sonnet-4-6", provider: :anthropic },
+  { model: "openai/gpt-5", provider: :openrouter }
+)
+```
+
+Every fallback must name its provider. Smith does not inherit the primary
+model's provider or infer one from the model id; an unqualified fallback fails
+closed during agent configuration.
+
 ### Full `Smith.configure` Example
 
 ```ruby
@@ -68,11 +83,11 @@ Smith.configure do |config|
     tool_call: %i[tool duration]
   }
   config.trace_content = false
-  config.trace_retention = 86_400
-  config.trace_tenant_isolation = false
+  config.trace_provider_calls = true
+  config.trace_attribution = true
 
   config.pricing = {
-    "gpt-4.1-nano" => {
+    %w[openai gpt-4.1-nano] => {
       input_cost_per_token: 0.0000001,
       output_cost_per_token: 0.0000004
     }
@@ -82,6 +97,12 @@ Smith.configure do |config|
 end
 ```
 
+Provider-qualified model calls require provider-qualified pricing keys. Smith
+also accepts the string form `"openai/gpt-4.1-nano"`. Legacy model-only keys
+remain available only for calls whose provider is genuinely unknown; if Smith
+observes a provider but finds only a model-only rate, it raises
+`Smith::PricingConfigurationError` instead of silently undercounting cost.
+
 ### What Each `Smith.configure` Setting Is For
 
 | Setting | What it controls | Typical first use |
@@ -94,11 +115,11 @@ end
 | `trace_transitions` | Emit transition traces | Usually leave on |
 | `trace_tool_calls` | Emit tool call traces | Usually leave on |
 | `trace_token_usage` | Emit usage traces | Useful for budget visibility |
-| `trace_cost` | Emit cost traces | Useful once pricing is configured |
+| `trace_provider_calls` | Emit one timed `:provider_call` trace per provider attempt | Usually leave on |
+| `trace_cost` | Emit one `:cost` trace per completed agent invocation | Emits only once pricing is configured |
 | `trace_fields` | Allowlist structural trace fields | Use when you want tighter trace output |
 | `trace_content` | Whether content appears in traces | Leave `false` first |
-| `trace_retention` | Trace retention policy hook | Useful when traces leave memory |
-| `trace_tenant_isolation` | Trace multi-tenant isolation flag | Enable in multi-tenant systems |
+| `trace_attribution` | Merge ambient execution attribution into trace payloads | Usually leave on |
 | `pricing` | Best-known model-call cost catalog | Add once you care about `total_cost` |
 | `logger` | Smith's runtime logger | Usually the first setting to add |
 | `persistence_adapter` | Adapter for durable workflow state | `:redis`, `:rails_cache`, `:active_record`, `:memory`, or a custom object |