smith-agents 0.12.1 → 0.12.3

data/docs/AGENTS.md

@@ -0,0 +1,241 @@
+# Agents
+
+How an agent's replies are checked, how its requests are shaped for each
+provider, and the two other ways a step can call it: streamed, and in batch.
+
+## Registering agents
+
+Agents register at class load. In Rails, register workflow-facing agents in a `to_prepare` hook so autoload doesn't drop them:
+
+```ruby
+# config/initializers/smith_agents.rb
+Rails.application.config.to_prepare do
+  ReplyAgent
+  TriageAgent
+end
+```
+
+## Agent outputs
+
+Smith reads how each response ended from the provider's stop reason. A
+response cut off at its output limit, a refused one, and a structured output
+that is not what the agent declares are not accepted as the step's output:
+
+```ruby
+class Reviewer < Smith::Agent
+  model "claude-opus-5-5", provider: :anthropic
+  output_schema ReviewSchema                         # its root is an object
+  output_contract ReviewContract                     # call(hash) => true, false, or a result with success? and errors
+  output_repairs 1                                   # the default; 0 turns repair off
+  on_truncation retry_with: { max_tokens: 64_000 }   # or :fail (the default), or :accept
+  on_refusal fallback: "openai/gpt-5"                # or :fail (the default)
+end
+```
+
+- A cut-off response raises `Smith::OutputTruncated`, unless the agent
+  accepts it or retries it once on the same model with a larger output limit,
+  mapped to the provider's own parameter (Anthropic, OpenAI, Gemini, Vertex AI
+  and Bedrock; another provider is not retried). There is no retry when the
+  response ran out of context rather than output, or when the new limit is no
+  larger than the request had (the agent's own parameter, or for Anthropic the
+  model's maximum, which RubyLLM already sends); a later repair keeps the
+  larger limit.
+- A refused response (a Gemini prompt block included) raises
+  `Smith::OutputRefused`, unless the agent falls back once to another model.
+- Every other response then goes through the agent's `after_completion`. A
+  structured output (an `output_schema`, or a static RubyLLM `schema`) that is
+  not a JSON object, breaks a schema constraint, or fails the output contract
+  goes back to the same model up to `output_repairs` times: the step's messages
+  as the provider got them, the rejected reply as the assistant's, and the
+  problems as "path: problem" lines. It then raises `Smith::OutputInvalid`,
+  whose `problems` lists at most 20 of them. A blank output still raises
+  `Smith::BlankAgentOutputError`.
+- No follow-up call is made once a tool has run in the step (the tools would
+  run again; the step fails with `Smith::ToolOutcomeUncertain` around the output
+  error) or once the call has spent what its step reserved from a budget. A
+  follow-up that fails raises the output error it was making up for, with the
+  provider's error as its cause.
+- Anthropic's structured outputs reject numeric, string-length and most
+  array-size constraints: Smith sends Anthropic the schema without them, with
+  `additionalProperties: false` on every object, and checks them on the parsed
+  output for every provider. An object that allows other properties or
+  declares none cannot be sent to Anthropic; the step fails before the call
+  with a `Smith::WorkflowError`, and runtime readiness reports
+  `:output_schema_unsupported` for an agent declared for Anthropic.
+- An agent with no model and no fallback models fails its step with a
+  `Smith::WorkflowError`; runtime readiness reports it (`:agent_without_model`).
+
+Every response is billed and settles into budgets, whatever happens to its
+output, and each rejected one leaves an `:output_rejected` trace naming its
+attempt. The output errors share the failure family `output_failure`, persist
+with a failed step, and are never retried by `Smith::Errors.retryable?`, a job
+retry on `Smith::Errors.retryable_classes`, or a transition's
+`retry_on Smith::AgentError`: Smith's own retry, fallback and repairs have run.
+
+## Models and request shaping
+
+Smith ships a per-attempt normalizer that translates the request payload to whatever the resolved model's provider family expects:
+
+- Anthropic Opus 4.7+ adaptive thinking via `output_config[:effort]`
+- Anthropic 4.0–4.6 budget_tokens
+- 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(...))`.
+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.
+
+## Streaming
+
+An agent step can send its reply's text to the host as the model writes it:
+
+```ruby
+# Called when a streamed step starts; returns the step's sink, or nil to
+# stream nothing (nobody is watching). Each step execution gets its own.
+Smith.config.stream_sinks = {
+  answer: ->(info) { AnswerStream.new(info[:execution_key]) if Screens.watching?(info[:execution_key]) }
+}
+
+class AnswerStream
+  def initialize(key)
+    @key = key
+    @reply = Smith::Streaming::JsonField.new(:reply)  # the output schema's reply field, as it grows
+  end
+
+  def delta(text) = (piece = @reply.push(text)) && Screens.append(@key, piece)
+  def reset(_reason) = @reply.reset || Screens.clear(@key)
+  def finish(output) = Screens.final(@key, output["reply"])
+  def fail(_error_class) = Screens.failed(@key)
+end
+
+class Answer < Smith::Workflow
+  initial_state :asked
+  state :failed
+
+  transition :answer, from: :asked, to: :answered do
+    execute :answerer, stream: :answer, output_to: :answer
+    on_failure :fail
+  end
+end
+```
+
+A sink defines any of `start(info)` (each provider call: the step's info with
+the attempt, model and provider), `delta(text)` (each text chunk; tool calls,
+thinking and `<think>` text are not sent), `reset(reason)` (Smith discarded the
+text sent so far: `:retry`, `:fallback`, `:truncation` or `:repair`; and
+`:retry_wait`, the last word, while a durable retry waits), `finish(output)`
+(the output the step accepted, after guardrails, the output contract and
+`output_to:`, once the step is stored) and `fail(error_class)`. Streamed text is
+a draft: guardrails and output checks run on the whole reply, so nothing should
+be saved or acted on before `finish`, and a step with an output schema streams
+JSON text (`Smith::Streaming::JsonField` gives the text each delta adds to one
+string field). A sink that raises is logged and the step goes on; a sink name
+that is not registered fails the step before its call. Stop reasons are read
+from the stream, so cut-off and refused replies are handled as without it, and a
+stream that ends without one counts as cut off (`stream_incomplete`). Smith's
+OpenAI Responses path does not stream: its sink gets each reply as one delta.
+Streaming changes nothing durable (each usage entry keeps its response's stop
+reason and message id, with `mode: :stream`), and a replayed step streams again
+(unless a response memo kept its reply: then its sink gets the text at once).
+Graph inspection shows the stream, and runtime readiness reports a missing sink
+(`:stream_sink_missing`) and an agent whose calls go to the Responses API
+(`:stream_whole_replies`).
+
+## Batch mode
+
+An agent step, or a fan-out, can send its requests through a provider's batch
+API (half price, answered within 24 hours) instead of over the wire:
+
+```ruby
+# The host keeps each request until a scheduled job submits it (a table, in
+# production); enqueue is idempotent on custom_id.
+class HostBatchQueue
+  Entry = Struct.new(:custom_id, :await_token, :request, :run_key, :batch_id)
+
+  def initialize = @entries = {}
+  def enqueue(custom_id:, await_token:, request:, execution_key:)
+    @entries[custom_id] ||= Entry.new(custom_id, await_token, request, execution_key)
+  end
+  def unsubmitted = @entries.values.reject(&:batch_id)
+  def entry(custom_id) = @entries.fetch(custom_id)
+end
+Smith.config.batch_queue = HostBatchQueue.new
+
+class Triage < Smith::Workflow
+  initial_state :queued
+  state :failed
+
+  transition :triage, from: :queued, to: :triaged do
+    execute :triager, mode: ->(ctx) { ctx[:urgent] ? :sync : :batch }, output_to: :verdict
+    on_failure :fail
+  end
+end
+
+# One scheduled job submits what is queued; another collects an ended batch
+# and resumes each run once with every result of its wait.
+queue = Smith.config.batch_queue
+batches = Smith::Providers::Anthropic::Batches.new
+entries = queue.unsubmitted
+batch_id = batches.submit(entries.map { { custom_id: _1.custom_id, request: _1.request } })
+entries.each { _1.batch_id = batch_id }
+if batches.status(batch_id)[:status] == "ended"
+  payloads = Hash.new { |hash, wait| hash[wait] = {} }
+  batches.results(batch_id) do |custom_id, result|
+    entry = queue.entry(custom_id)
+    payloads[[entry.run_key, entry.await_token]][custom_id] = result
+  end
+  payloads.each { |(run_key, token), payload| Triage.resume!(run_key, event: :batch_result, token:, payload:) }
+end
+```
+
+`mode:` is `:sync` (the default), `:batch`, or a callable of the context and
+the step attempt returning one, on `execute` and `fan_out`; a batch step
+declares `on_failure`, and cannot stream or be `parallel:`. Smith prepares
+the call as a synchronous one, admits it against the budget, and hands the
+exact request (the provider payload and the call's own headers, never the
+connection's credentials) to the queue under a `custom_id` (the wait's token;
+each fan-out branch its own) once the step's attempt has ended without error,
+then the run waits on `:batch_result`. Smith never submits or polls, and waits
+without sleeping: `Smith::Providers::Anthropic::Batches` gives the host
+`submit`, `status`, `results` and `cancel`. `resume!` with
+`{custom_id => result}` runs the step again, each call taking its result as
+the reply it would have got. A call that renders another request by then (a
+date in its prompt, data read afresh, a prompt changed in a deploy; a prompt
+cache marker added or dropped is no change, as it never changes what the
+request asks, though a request captured by Smith 0.12.2 is matched as it was
+sent, markers included) does what
+its step's `on_request_change:` says: `:keep` (the default) takes the result,
+which answers the request as sent, and its `:provider_call` trace says
+`request_changed: true`; `:resend` sends the request as rendered now over the
+wire instead; `:fail` fails the step with `Smith::BatchRequestChanged` (an
+`AgentError`, so `retry_on` can send it again, synchronously if the mode
+callable says so). A result the call does not use is charged all the same.
+Then the output checks, a follow-up call (over the
+wire), guardrails and `output_to:` as ever, usage recorded with `mode: :batch`
+and priced with the catalog's `batch_discount`, and charged even past a
+budget, as the money is spent. A request the provider refused fails the step
+(`Smith::BatchRequestInvalid`); a failed, canceled or expired result, or none
+by the wait's deadline (`expire_wait!`, 25 hours), raises
+`Smith::BatchResultFailed`, which `retry_on` sends again (synchronously, if the
+mode callable says so at the next attempt; an in-process `retry_on` backoff
+sleeps as on any step, while `durable: true` waits). Only Anthropic's batch interface is
+built in, and a batch request is one turn, so a batching agent has no tools;
+runtime readiness reports a missing queue (`:batch_queue_missing`) and an
+agent that cannot batch (`:batch_unavailable`), and graph inspection shows the
+mode.

data/docs/BUDGETS.md

@@ -0,0 +1,134 @@
+# Budgets and Deadlines
+
+```ruby
+class BudgetedWorkflow < Smith::Workflow
+  budget total_tokens: 10_000, total_cost: 0.50, wall_clock: 30
+end
+```
+
+`wall_clock` is in seconds. A workflow's `wall_clock` bounds the time its steps
+spend running, counted across restores in the persisted `active_seconds`, not
+the time since the run was created: time spent waiting, or between steps a host
+advances from a queue, does not count. A step that raised or whose process died
+(or met an interrupting error) is charged, on the next restore, the time from its start, at most what is left
+of the budget, so a run that keeps failing stays bounded across retries.
+Durable composite branches each start from what is left; their running time is
+not added back. An agent's `wall_clock` bounds each of
+its calls. A workflow budget accepts `total_tokens`,
+`token_limit`, `total_cost`, `tool_calls`, and `wall_clock`; an agent budget
+accepts `token_limit`, `cost`, `wall_clock`, `tool_calls`, `total_tokens`, and
+`total_cost`. Any other key raises `ArgumentError` naming the accepted keys. A
+restored run drops consumed amounts for keys the workflow no longer declares.
+
+Budgets reserve serially at each step and reconcile after the agent call. Parallel branches reserve scoped envelopes that release back to the parent ledger. The `Workflow::RunResult` carries `total_tokens`, `total_cost`, and per-call `usage_entries`. Token budgets and totals count prompt-cache reads and writes beside uncached input and output, and settle every billed response, including the completed rounds of a tool loop whose attempt then failed.
+
+Direct ledger integrations settle the exact receipt returned by reservation:
+
+```ruby
+reservation = ledger.reserve_many!(total_tokens: 1_000, total_cost: 0.10)
+ledger.reconcile_many!(reservation, actual: { total_tokens: 640, total_cost: 0.06 })
+```
+
+`release!` / `release_many!` accept the same receipt when work never starts.
+Receipts are ledger-owned and one-shot: another ledger, a replay, or an
+amount-only settlement is rejected. `ledger.remaining(key)` never reads back
+above the exact remaining amount, and `ledger.remaining_share(key, parts)`
+returns one of `parts` equal shares of it such that reserving all `parts` fits.
+
+Budget amounts accept finite, non-negative `Integer` and `Float` values. Smith
+uses an exact `BigDecimal` representation derived from each value's canonical
+decimal text and converts ledger snapshots back to ordinary JSON-safe numerics,
+avoiding cumulative binary Float drift without changing persisted workflow
+state shapes. Ledger arithmetic temporarily uses unlimited decimal precision and
+restores the host's existing `BigDecimal` precision limit before returning.
+
+Budget operations are atomic for normal concurrent callers and synchronous
+exceptions. Smith uses cooperative cancellation and never terminates branch
+threads with `Thread#raise` or `Thread#kill`. Arbitrary asynchronous thread
+termination can make any in-process return value outcome-ambiguous; hosts must
+use cancellation signals, bounded I/O, and process isolation for hard stops.
+
+## Budget ledgers
+
+A run's `budget` bounds that run. A budget shared by many runs (an account's
+monthly spend, say) lives in the host, and a workflow names it with
+`budget_ledger`:
+
+```ruby
+class MonthlyLedger
+  def initialize(account) = @account = account
+
+  # Admit the hold (true; anything else refuses it) and keep it under key
+  # until expires_at, after which it counts for nothing.
+  def reserve!(amount, key:, expires_at:) = ...
+  def reconcile!(key, amount) = ...   # what the request spent, in place of its hold
+  def release!(key) = ...             # it spent nothing
+end
+
+class DocumentReview < Smith::Workflow
+  budget_ledger(:account_id) { |scope| MonthlyLedger.new(scope[:account_id]) }
+end
+```
+
+The block gets the run's scope: the values the named keys have in its trusted
+context when the run is created (JSON scalars, kept with the run), so nothing a
+step or a model writes later chooses another ledger, and an untrusted key is
+refused. Smith builds the ledger at the first request a step makes, never
+persists it, and never needs it to restore a run; nil means none. A nested
+workflow without a `budget_ledger` of its own charges the enclosing run's; a
+child run (`call`, `map`, `spawn`), inline or not, uses its own class's, so
+give each child workflow its own (runtime readiness warns of one that has none,
+`:child_run_unbudgeted`) and pass its scope keys in each child's input.
+
+Before a call's first request over the wire (each fallback model, each
+follow-up, streamed or not, OpenAI's Responses route included) Smith asks the
+ledger to admit its hold. If the ledger refuses, the step fails with
+`Smith::BudgetUnavailable` (a `BudgetExceeded`, not retried by default) before
+anything is sent; `retry_on Smith::BudgetUnavailable, durable: true, ...` waits
+for budget instead (the host ends the wait with `expire_wait!`, and ends it
+early, once there is budget, with a `now:` at its `deadline_at`). After the request, Smith reconciles what it
+spent: its usage, or its hold when it answered without usage or its stream
+failed part way; a request that failed before anything came back releases its
+hold. If building the ledger or `reserve!` raises, the step fails with
+`Smith::BudgetLedgerError` (nothing was sent, no fallback model is tried); one
+from `reconcile!` or `release!` is logged by class and the step goes on, as
+the money is spent.
+
+A tool loop's later rounds continue a call whose tools already ran, so
+stopping one would leave the tools' effects without their answer. A step whose
+`retry_on` names `BudgetUnavailable` holds them too: when the ledger refuses
+one, the loop pauses, keeping its tool calls and their results (at most 1 MiB)
+with the step's retry, and the retry continues the loop from them, running
+none of its tools again. Any other step's later rounds, or a loop too large to
+keep, go on unheld and are reconciled with what they spent, so give tool-using
+agents a `tool_calls` budget.
+
+A hold (`Smith::Budget::Amount`: `input_tokens`, `output_tokens`, `cost`, and
+`tokens`, their sum) is the request's output cap (its `max_tokens`, or its
+provider's name for it, else the model's) and an estimate of its input: text
+at one token per 3 bytes, an image at 1,600 tokens, a PDF at 2,000 tokens a
+page, 8 tokens a message for its framing, capped at the model's context window.
+Images and documents count so as RubyLLM attachments and in raw content blocks
+(base64 data or a data URL). `Smith.config.budget_hold_output_tokens`, when
+set, caps the output part (an agent with no `max_tokens` is otherwise held for
+the model's maximum, which can be tens of thousands of tokens, and a longer
+reply is reconciled at what it cost). It is priced from the pricing catalog
+under the id RubyLLM resolves the model to; `cost` is nil for an unpriced
+model, which runtime readiness warns of (`:budget_ledger_unpriced`, for every
+agent that charges the ledger), and its readiness metrics name the scope keys.
+
+A key is the provider attempt's `attempt_id` (as on its `:provider_call` trace)
+and the request's round, `"<attempt_id>:<n>"`, and for a batch request its
+`custom_id`. A batch request is held when its step captures it, at the batch
+discount, and settled when its result comes: a succeeded result, used or not,
+is reconciled at what it cost; one that failed, or never came, is released.
+A process that dies during a request never settles its hold, so every hold
+carries `expires_at`: `Smith.config.budget_hold_ttl` from now (an hour by
+default; it must outlast the longest request), and for a batch request its
+25-hour wait longer. Smith runs no timer; the ledger leaves holds past
+`expires_at` out of what it admits, and still records a reconcile that comes
+later (a batch delivered late). A key may come again after a crash (a batch
+request captured again, a delivery that ran twice): a reserve of it replaces
+its hold, a release ends it, and its reconcile is final, recorded once.
+Fan-out branches call the ledger from their own threads. RubyLLM's own retries
+(`max_retries`) resend a request under its one hold.

data/docs/CONFIGURATION.md

@@ -30,7 +30,7 @@ Use agent classes for invocation behavior:
 - `fallback_models`
 - `register_as`
 
-The output macros are described in the README, Agent outputs.
+The output macros are described in [AGENTS.md](AGENTS.md), Agent outputs.
 
 ### 3. Workflow configuration: `Smith::Workflow`
 
@@ -115,8 +115,33 @@ Smith.configure do |config|
   # Batch steps (`execute Agent, mode: :batch`): the host's queue of requests.
   config.batch_queue = HostBatchQueue.new
 
-  # How long a request's hold on a workflow's budget_ledger lasts unsettled.
+  # How long a request's hold on a workflow's budget_ledger lasts unsettled,
+  # and the most output tokens a hold counts (nil: the request's own cap).
   config.budget_hold_ttl = 3600
+  config.budget_hold_output_tokens = nil
+
+  # Persistence: where runs are stored, and a stored state's bound.
+  config.persistence_adapter = :active_record
+  config.persistence_options = { model: "WorkflowState" }
+  config.persistence_ttl = nil              # :active_record cannot expire state
+  config.persistence_max_bytes = 16_777_216 # nil: no bound
+  config.persistence_retry_policy = { attempts: 3, base_delay: 0.1, max_delay: 1.0 }
+
+  # Child runs (`call`, `map`, `spawn`) and replays.
+  config.run_launcher = HostLauncher.new
+  config.response_memo = HostResponseMemo.new
+
+  # Errors that stop a step as if its worker had stopped, instead of failing it.
+  config.interrupting_errors = [ActiveRecord::ConnectionNotEstablished, ActiveRecord::ConnectionFailed]
+
+  # Generic runtime resource bounds.
+  config.parallel_branch_limit = 1_000
+  config.parallel_concurrency = 8
+  config.parallel_nesting_limit = 64
+  config.retry_attempt_limit = 100
+
+  # OpenAI /v1/responses routing for gpt-5 + tools + thinking: :auto (default) or :off.
+  config.openai_api_mode = :auto
 
   config.logger = Logger.new($stdout)
 end
@@ -169,7 +194,8 @@ from JSON or YAML has.
 | `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 |
 | `batch_queue` | Takes the requests `mode: :batch` steps send: `enqueue(custom_id:, await_token:, request:, execution_key:)`, idempotent on `custom_id`; the host submits them (`Smith::Providers::Anthropic::Batches`) and resumes each run with its results | Set before any workflow batches; readiness reports a missing one |
-| `response_memo` | Keeps what a step's provider calls got (`fetch(key)`, `store(key, record)`), so a step replayed after its process died reuses it instead of paying again (README, "Response memo") | Set it where replays happen: lax idempotency mode, or a host that runs a crashed step again |
+| `response_memo` | Keeps what a step's provider calls got (`fetch(key)`, `store(key, record)`), so a step replayed after its process died reuses it instead of paying again ([ERRORS_AND_RETRIES.md](ERRORS_AND_RETRIES.md), Response memo) | Set it where replays happen: lax idempotency mode, or a host that runs a crashed step again |
+| `interrupting_errors` | Subclasses of StandardError that interrupt a step instead of failing it, such as the host's database or queue out of reach: met in a step (or as the cause of an error that was, never through a provider's own failure), they take no route, no retry and no failure record, reach the caller as raised, and leave the run as the step left it. Smith does not count them ([ERRORS_AND_RETRIES.md](ERRORS_AND_RETRIES.md), Interrupting errors). None by default | Name the errors that mean your own systems failed, never ones a step can cause every time (a query timeout) |
 | `budget_hold_ttl` | Seconds a provider request's hold on a workflow's `budget_ledger` lasts unsettled (default 3600): each hold's `expires_at` is this from now, and a batch request's is its 25-hour wait longer. Past it the request's process is taken to have died | Raise it above the longest request (its retries and stream included) |
 | `budget_hold_output_tokens` | The most output tokens a request's hold on a workflow's `budget_ledger` counts (default nil: the request's own `max_tokens`, else the model's maximum). Only the hold changes, not the request; a longer reply is reconciled at what it cost | Set it when agents leave `max_tokens` unset and a small budget would refuse calls on their huge holds |
 | `stream_sinks` | The sinks `execute Agent, stream: :name` steps send text to, by name: callables that take a step's info (`stream`, `execution_key`, `transition`) and return that step's sink, or nil to stream nothing | Register each name a workflow streams to; readiness reports a missing one |

data/docs/DEVELOPMENT.md

@@ -0,0 +1,63 @@
+# Developing Smith
+
+## Verification discipline
+
+Tests are required, but they are never enough for runtime primitive changes.
+Every Smith workflow slice must also run practical gem-level execution probes.
+When a host application consumes unreleased Smith changes, point that host app at
+the local Smith repository and exercise the changed workflow paths in the host
+environment before calling the slice complete.
+
+## Algorithms
+
+Smith changes must not use brute-force graph search, validation, scheduling, or
+class-generation algorithms. Document the relevant time and space complexity,
+prefer indexed, linear, logarithmic, or otherwise bounded approaches, and treat
+an avoidable asymptotic regression as a release blocker.
+
+## Runtime complexity
+
+- 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
+  only idle workers from the top-level execution context, falling back to the
+  current worker when no capacity remains. Nested calls fail closed before the
+  configurable nesting bound can exhaust Ruby's stack. Cancellation prevents
+  queued branch bodies from starting;
+  already-running branches are drained before control returns so work is never
+  detached. Branch adapters must use bounded I/O and honor the cancellation
+  signal. Hosts continue to own process-level concurrency and hard deadlines.
+- Reservation and settlement across `L` declared budget dimensions and `D`
+  operation dimensions is `O(L + D)` time and space. Receipt lookup is expected
+  `O(1)`; no operation scans or copies the active receipt registry. Integer and
+  Float amounts use exact decimal arithmetic internally.
+- Retry delay calculation is `O(1)` time and space per attempt. A policy with
+  `A` attempts performs at most `A` guarded operations and never materializes an
+  exponential schedule.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```

data/docs/ERRORS_AND_RETRIES.md

@@ -0,0 +1,177 @@
+# Errors and Retries
+
+```ruby
+Smith::Errors.retryable?(error)
+# AgentError, DeadlineExceeded => true (always)
+# OutputTruncated, OutputRefused, OutputInvalid (OutputFailure) => false
+# DeterministicStepFailure, ToolGuardrailFailed => honors error.retryable
+# everything else => false
+
+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
+```
+
+A nested workflow's step fails with the child's own error when the child
+raises it, so these answers carry through nesting. When a tool ran inside the
+child, the parent step's failure becomes `ToolOutcomeUncertain`, which is never
+retried.
+
+Workflow transitions can also declare a bounded local retry policy:
+
+```ruby
+transition :draft, from: :idle, to: :done do
+  execute :writer
+  retry_on Smith::AgentError, attempts: 3, backoff: 0.1, max_delay: 1.0
+end
+```
+
+When no classes are passed, `retry_on` uses `Smith::Errors.retryable?`. No
+attempt starts once the workflow's wall-clock deadline has passed.
+This is a bounded local transition retry policy. What a receiver does with an
+idempotency key remains host-owned.
+
+For backoffs too long to sleep through in a worker, `durable: true` makes each
+one a wait of the run instead:
+
+```ruby
+transition :charge, from: :approved, to: :charged do
+  compute { |step| Payments.charge(order, idempotency_key: step.idempotency_key) }
+  retry_on Payments::Timeout, attempts: 5, backoff: 60, max_delay: 3600, durable: true
+  on_failure :charge_failed
+end
+```
+
+A failed attempt the policy retries stores the run waiting (`awaiting.kind ==
+:retry`, due when the backoff ends); the host schedules `expire_wait!` for that
+time and then continues the run, which makes the next attempt under the step's
+keys (new ones only after an attempt declared settled). See
+[PERSISTENCE.md](PERSISTENCE.md), Durable Retry.
+
+Steps and tools get idempotency keys for the requests they send outside the
+system, the same on every attempt and after a restore:
+
+```ruby
+transition :charge, from: :approved, to: :charged do
+  compute { |step| Payments.charge(order, idempotency_key: step.idempotency_key) }
+  retry_on Payments::Timeout, Payments::Declined, attempts: 3,
+           new_idempotency_key_on: [Payments::Declined]
+end
+```
+
+A retry keeps the keys, so a receiver that honours them drops a request that
+took effect before a timeout. An error named in `new_idempotency_key_on:` (or
+`step.fail!(..., new_idempotency_key: true)`) shows the attempt's own requests
+took no effect, and the attempts after it use new keys. See
+[PERSISTENCE.md](PERSISTENCE.md), Replay Safety.
+
+## Interrupting errors
+
+Some errors say the host could not do its part, not that a step went wrong:
+its database or its queue out of reach for a moment. Named as interrupting,
+they stop a step where it is, as if its worker had stopped, instead of
+failing it:
+
+```ruby
+Smith.config.interrupting_errors = [
+  ActiveRecord::ConnectionNotEstablished,
+  ActiveRecord::ConnectionFailed,
+  Smith::PersistenceIOError
+]
+```
+
+A step meets one when it is raised anywhere in the step (a compute block, a
+tool, a tool failure handler, a guardrail, a budget ledger, a nested or
+inline child run, a parallel branch) or is one of the first 15 causes of an
+error that was. Smith then takes no failure route, makes no retry
+(`retry_on`, durable ones included), records no failure (`last_failed_step`,
+`StepFailed`; a deterministic step's trace says `outcome: :interrupted`),
+notifies no tool failure handler and keeps no failed branch outcome. The
+error itself, not one that wrapped it, reaches the caller of `advance!`,
+`advance_persisted!`, `run!`, `run_persisted!`, or of `resume!` when the
+delivery completes a batch step; among parallel branches and tools run
+together it wins over every other error but a process-fatal one. The run's
+stored state is as the step left it: a lax run takes the step again, under
+the same idempotency keys and with the response memo's answers, when it is
+next advanced; a strict run is found under way on restore
+(`Smith::StepInProgressOnRestore`), as after a crash. The instance that
+raised is not advanced again: restore the run.
+
+Name only errors that mean your own systems failed. A provider's own failure
+(`RubyLLM::Error`, or its HTTP client's `Faraday::Error`) is the provider's
+whatever it was raised from, so naming a low-level class such as
+`Errno::ECONNREFUSED` never turns a provider outage into an interruption;
+name the provider's class itself for that. Smith does not count
+interruptions: a step that meets one every time (a query of its own that
+always times out, if `ActiveRecord::StatementTimeout` were named) is taken
+again for as long as the host keeps advancing it, so the host bounds it, by
+its job's retries or a count of its own. A `wall_clock` budget is charged as
+after a crash: on restore, the time from the step's start, an outage
+included, at most what is left.
+
+A response memo, a trace adapter, a stream sink, an event handler, an
+`on_step` callback, a `capture_result` block that is not strict, and a budget
+ledger's `reconcile!` and `release!` log one they meet and go on, as they do
+any error of their own. Only subclasses of StandardError can be named, never
+StandardError itself. None are named by default, so every error takes its
+step's route.
+
+## Response memo
+
+A step replayed after its process died makes its provider calls again, and
+pays for them again. A host's response memo keeps what they got:
+
+```ruby
+class ResponseMemo
+  def fetch(key) = Rails.cache.read("smith-memo/#{key}")
+  def store(key, record) = Rails.cache.write("smith-memo/#{key}", record, expires_in: 2.days)
+end
+
+Smith.config.response_memo = ResponseMemo.new
+```
+
+Each agent call (its tool loop included) is kept under a key of its position
+(the run, the step, any branch or nested position, the key generation), the
+attempts it runs under (its step's, and each enclosing run's for a nested
+workflow, so a retry never takes the attempt before's answer), its attempt
+index (its model in the fallback chain, or a follow-up's place), its place
+among the attempt's calls, and a digest of its request (model, messages,
+tools with their descriptions and parameters, schema, params), Anthropic's
+prompt-cache markers aside: whether a part is cached never changes what the
+call asks, so a host may decide it call by call, keeping the part's form (the
+same text block, with or without its marker). A replay reaches the same key; a
+call whose request changed since (a deployed prompt or tool, another model, a
+date in the prompt) misses and is sent again, as a miss always may be.
+
+Its record (`{"version" => 1 | 2, "messages" => [...], "complete" => true |
+false}`, JSON) holds the messages the call added: the model's replies
+(structured ones too) with their usage, stop reason and message id (a
+stream's included), its tool calls and their results. It is stored when a
+reply calling the tools its request offered comes, before they run; before
+each later request, with their results; and when the call ends in the model's
+reply (a call a tool halted keeps only its progress). A replayed call that
+ended sends nothing: its reply is the step's (a streamed step's sink gets the
+reply's text at once, not the earlier rounds'), its usage is recorded as if it
+had just come, once, and its `:provider_call` trace says `memo: true`; a reply
+that was cut off or refused fails the step as it did. One that had not ended
+goes on from where it was kept. Kept after its tools' results, it continues
+from them: kept tool results count as tools the step ran, so no retry or
+fallback runs them again, and each is charged to the agent's `tool_calls`
+allowance and the workflow's `tool_calls` budget as it was. Kept while its
+tools ran (the step was cut inside a tool), the reply that called them is not
+asked for again: its tools run again, under the same idempotency keys, and the
+call goes on. Either way its live part goes on from the kept rounds (on a
+budget ledger, a later round, held only when the step can pause for budget).
+A call whose messages cannot be kept (an attachment, past 1 MiB) is not
+stored, and is logged; a record Smith does not keep (its shape, or tool
+results that do not answer the calls before them) is ignored, and an error
+from `fetch` or `store` is logged by class: a memo never fails a step. Only a
+record ending in a reply whose tools have not run is version 2, which a Smith
+before 0.12.2 ignores (paying for that reply again and running its tools, as
+it did); it reads every other record. Records for calls with tools that
+0.12.1 kept are not found after the upgrade, nor these by 0.12.1, since the
+digest now covers the tools' definitions. Keeping records and dropping them (a
+TTL) are the host's; batch requests are not memoized, as their `custom_id`
+already identifies them.