smith-agents 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 450ce06c1d96f41a8b6ae6d0c0dd1b8dcc88b58d3da786d8536a26ecc8f111bb
-  data.tar.gz: 7b0696ff9aaccc3016ebef5223c4ded71aeeb883d1a1b70e6f2ab5959657e1da
+  metadata.gz: 1fe948e343baa2573448f7a95a964729e96a71b0b2e6ef16226694400ba0fb97
+  data.tar.gz: 8f3d35e4ee6998ca41a4be0e19dcce0b5e843b44c0f28167aff3d5326d1be573
 SHA512:
-  metadata.gz: da3c5cb55ef7efac304f223eb7ce468f058b4d85c9c4b60ea102f50882789d067eaf9c2a212871eb66a215f7f1cce2baa29de945dd3c0f2c0cc084d187fec1ae
-  data.tar.gz: 910ec83bc644cdbb5ad1a737ef1aa95af3d5ca784d952fea9179ae4b7e44d49a1edf7a7ae2b067c7a83a227bb623d3d6c798cc45a8d254501ff397f99e876b69
+  metadata.gz: 85bc7336ef0cb273979c4c7df1a4c0c724eb74cb34c4b49c1b23768e9454c700a1f33827ac9a1b33ff9680efd55b302b282db0fc553c5e20c52b4d13970044fa
+  data.tar.gz: afe1281c6ef7967292c1c43b7370ca5ab3795abcc98722aa8e10c03266347dcd2411d9c44878f1c0d4aa41df5f88ffd636d46084ff996f2008f60baa650ce5fc

data/CHANGELOG.md

@@ -4,6 +4,232 @@ 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.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
@@ -72,7 +87,7 @@ Smith.configure do |config|
   config.trace_tenant_isolation = false
 
   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 |

data/docs/PERSISTENCE.md

@@ -12,7 +12,7 @@ Example:
 class ReviewContext < Smith::Context
   persist :ticket_id, :current_findings, :source_urls
 
-  session_strategy :observation_masking, window: 6
+  session_strategy :observation_masking, window: 6, preserve_seed: true
 
   inject_state do |persisted|
     <<~TEXT
@@ -37,12 +37,22 @@ end
 What Smith does for you:
 
 - prepares masked session input at step boundaries
+- optionally preserves the complete immutable `seed_messages` prefix, with its
+  original roles and order, while bounding only later workflow observations
 - injects a state summary message into that prepared input
 - persists declared workflow context keys
 - persists accepted session history
 - preserves chosen next transitions across persistence
 - supports JSON host round-trips through `to_state` and `.from_state`
 
+`preserve_seed: true` is intended for workflows whose seed is durable external
+conversation and whose later accepted outputs are internal stage handoffs. Smith
+persists and validates the exact seed-prefix length, so restart does not infer
+the boundary from message content. The masking pass is linear in session length
+and retains only the seed prefix, injected system messages, and the configured
+observation tail. Legacy state without `seed_message_count` restores with no
+preserved prefix.
+
 Example host-controlled persistence:
 
 ```ruby
@@ -305,6 +315,22 @@ and JSON serialization hooks. It is bound by object identity to one workflow
 instance and by process id to the issuing Ruby process, so a forked child cannot
 consume inherited authority. It is not a lease, cross-process fence, or durable
 attempt receipt.
+
+Persisted workflow failures use an explicit reconstruction registry. Smith does
+not resolve arbitrary class names from persisted data or invoke their
+constructors. Known retry-forbidden families retain their non-retryable
+semantics even when the original class is no longer available; unknown classes
+restore as `RuntimeError`. Failure messages and details are normalized into
+bounded JSON-safe evidence before persistence; invalid or oversized details are
+represented by an explicit omission marker. Inconsistent persisted class,
+family, retry-policy, or known typed-detail evidence fails closed during
+`from_state` as `Smith::PersistedFailureInvalid`. Failure capture uses native
+Ruby class and message operations so an exception cannot override diagnostic
+methods to suppress its durable terminal record. Terminal
+`Smith::ToolFailureNotificationFailed` records preserve bounded diagnostic
+details for both the dispatch failure and the failed host notification and
+restore as the same non-retryable failure family.
+
 Before consuming the capability, a host may inspect the exact captured agent
 bindings with a block: