smith-agents 0.7.0 → 0.8.0

data/docs/TOOLS_AND_GUARDRAILS.md

@@ -33,6 +33,91 @@ class RefundCustomer < Smith::Tool
 end
 ```
 
+`params` and Ruby keyword declarations describe the model-facing tool schema.
+Tool arguments remain untrusted. A host adapter must validate its own input
+contract inside `perform` before external work and return a bounded failure
+payload for expected validation or provider failures. It should raise for
+configuration, programming, authorization-integrity, or durability failures.
+Smith applies policy and budgeting around that host boundary; it does not
+interpret a host's input schema or failure envelope.
+
+### Bounded Completion
+
+The default exhaustion policy remains fail-fast:
+
+```ruby
+class SearchAgent < Smith::Agent
+  tools WebSearch
+  budget tool_calls: 3
+  tool_budget_exhaustion :raise
+end
+```
+
+Read-only agents that can finish from partial evidence may opt into graceful
+completion:
+
+```ruby
+class SearchAgent < Smith::Agent
+  tools WebSearch
+  budget tool_calls: 3
+  tool_budget_exhaustion :complete
+end
+```
+
+Hosts with signed per-tool policy can replace the aggregate integer with an
+exact budget:
+
+```ruby
+budget = Smith::Tool::CallBudget.new(
+  total: 4,
+  tool_limits: {
+    "weather_forecast" => 1,
+    "web_search" => 3
+  }
+)
+
+Smith::Tool.with_call_budget(budget, on_exhaustion: :complete) do
+  workflow.advance
+end
+```
+
+An agent may use the same value in `budget tool_calls: budget`. The enclosing
+allowance is a shared transition cap. Same-agent parallel branches,
+heterogeneous fan-out branches, and repeated optimizer participants narrow that
+shared cap to their own agent budget; they do not receive independent copies.
+Batch admission checks the aggregate and per-tool counters atomically before
+any tool runs.
+
+`:complete` requires a finite budget and RubyLLM 1.16.0. While more than one
+call remains, Smith permits the provider to return multiple calls in one
+response; the final remaining call uses the single-call provider hint. Smith
+still executes an admitted batch sequentially and advances the provider loop
+iteratively without recursive Ruby stack growth. The provider control is
+advisory: every returned batch is checked atomically. A batch larger than the
+remaining allowance executes no calls, receives one tool result for every
+requested call id, and is followed by one completion with the tools removed.
+Exact exhaustion follows the same tool-disabled completion path. The original
+tools, call preferences, and concurrency setting are restored in `ensure`.
+
+The allowance counts model-requested calls, including unavailable tool names.
+An exact admitted Smith tool receives a one-use admission so it is not charged
+twice; a nested Smith tool must consume its own allowance. Batch admission
+reserves the effective workflow tool budget before any tool runs, then
+reconciles calls rejected before `perform`. Calls on the same bounded chat
+cannot complete concurrently or reenter through callbacks. The opt-in bounded
+policy accepts only `Smith::Tool` bindings so Smith can enforce these guarantees;
+ordinary RubyLLM tools retain their existing behavior when the policy is not
+enabled. Raw provider params may not override `tools`, tool choice, or parallel
+tool-call controls while bounded completion is active. Smith supplies the
+provider call-cardinality hint only when the RubyLLM model registry advertises
+`parallel_tool_calls`, or when the selected Responses endpoint supports that
+control. Otherwise the hint is omitted and Smith's atomic local batch admission
+remains authoritative.
+
+This is not a durable model-loop checkpoint. A host still needs an operation
+receipt and reconciliation boundary before replaying side effects or recovering
+mid-loop from process loss.
+
 ### Tool Compatibility (provider-aware tool selection)
 
 Tools can declare which provider/endpoint combinations they tolerate. `Smith::Models::Normalizer` consults this metadata at chat construction and drops incompatible tools rather than letting the provider reject the request. Tools without a declaration are universally compatible (preserves existing behavior).
@@ -48,7 +133,10 @@ class WebSearch < Smith::Tool
 end
 ```
 
-When `Smith.config.openai_api_mode = :auto` (the default) AND the tool requires `/v1/responses`, the normalizer instead sets `@params[:openai_api_mode] = :responses` so the routing prepend can dispatch via the Responses endpoint. When `:off`, the tool is dropped gracefully.
+When `Smith.config.openai_api_mode = :auto` (the default) AND the tool requires
+`/v1/responses`, the normalizer sets `@params[:openai_api_mode] = :responses` so
+the routing prepend can dispatch via the compatible endpoint. This applies with
+or without model thinking. When `:off`, the tool is dropped gracefully.
 
 The compatibility spec is inherited by subclasses; subclasses can override by calling `compatible_with` again. The spec is consulted only by the Normalizer, so tools without a declaration retain their pre-refactor behavior.
 
@@ -136,11 +224,154 @@ requiring Smith does not alter raw RubyLLM chats. Arbitrary chats, threads, or
 fibers created by host code are outside this boundary and must install their own
 scope. Hosts remain responsible for using an immutable value and installing a
 fresh context after durable resume; context-dependent adapters must fail closed
-when no context is installed. Smith supports RubyLLM `>= 1.15, < 1.17` for this
+when no context is installed. Smith supports RubyLLM `1.16.0` for this
 integration and fails closed if the required per-chat tool execution hook is
 unavailable. RubyLLM fiber concurrency still requires its optional `async`
 dependency; Smith does not make that scheduler a runtime dependency.
 
+Smith applies the same model normalization and tool-compatibility routing to
+persisted chats returned by `create`, `create!`, and `find` as it does to direct
+`chat` construction. The configured transport provider is authoritative even
+when the model identifier is commonly associated with another provider;
+provider-specific endpoint assumptions are cleared when the transport changes.
+Reserved Smith inputs are available before persisted-chat dynamic
+configuration runs. When OpenAI endpoint routing is automatic, Smith compares
+the compatible tool counts in one pass and selects Responses only when it
+preserves a strictly larger subset; a tie keeps the current endpoint. A
+specific forced tool takes precedence when only one enabled endpoint can carry
+it. If normalization removes a specifically forced tool, Smith clears that
+stale choice and attributes the reset only to that selected tool. An
+endpoint-constrained tool routed to OpenAI Responses inherits the current
+non-streaming Responses contract; callers requesting streaming receive the
+documented explicit unsupported error rather than silent Chat Completions
+fallback.
+
+Bounded completion ownership and tool-call reservations mask asynchronous
+interrupts while installing and restoring process-local state. User work runs
+with normal interrupt delivery, and the protected cleanup finishes before an
+interrupt can escape the boundary.
+
+During an executing Smith tool, hosts can also read immutable normalized call
+metadata:
+
+```ruby
+invocation = Smith::Tool.current_invocation
+invocation.tool_call_id
+invocation.tool_name
+invocation.ordinal
+invocation.batch_ordinal
+invocation.batch_size
+```
+
+`tool_call_id` is RubyLLM's normalized call identifier. Some adapters preserve
+an identifier supplied by the model provider and others synthesize one while
+parsing, so it is correlation metadata, not a provider idempotency key or
+authoritative replay proof. `ordinal` is allocated from one thread-safe sequence
+shared by every Smith-managed chat, branch, thread, and fiber inside the current
+host invocation scope.
+
+Hosts that reconstruct an execution may supply an explicit next ordinal:
+
+```ruby
+sequence = Smith::Tool::InvocationSequence.new(next_ordinal: 12)
+Smith::Tool.with_invocation_context(context, invocation_sequence: sequence) do
+  workflow.advance
+end
+```
+
+Smith does not persist that sequence. A durable host must derive the resume
+ordinal from its own authoritative ledger and must not resume a model/tool loop
+unless it can also reconstruct the exact provider transcript and operation
+outcomes. Without an invocation context Smith uses a chat-local sequence for
+ordinary non-hosted tool execution.
+
+Durable hosts may atomically admit the complete Smith-managed subset of each
+provider batch before Smith dispatches any Smith tool:
+
+```ruby
+Smith::Tool.with_invocation_context(
+  context,
+  invocation_sequence: sequence,
+  batch_admitter: ->(requests:) { receipts.admit_batch!(requests) },
+  failure_handler: ->(request:, error:) { receipts.fail_dispatch!(request, error) }
+) do
+  workflow.advance
+end
+```
+
+Smith snapshots provider-batch membership once using native `Hash` operations
+after admitting its native cardinality, then verifies the owned snapshot retained
+that cardinality and validates provider-call identity. The complete provider
+batch is limited to 100 calls and 1 MiB of normalized UTF-8 call metadata before
+host admission; aggregate capture stops as soon as the metadata limit is crossed,
+before reading that crossing call's arguments. Every
+model-requested call, including unavailable and plain RubyLLM names, is reserved
+against the active Smith budget. For registered
+`Smith::Tool` targets Smith owns a bounded, acyclic, JSON-compatible argument
+snapshot and rejects duplicate string-equivalent object keys. It materializes
+one immutable dispatch collection from those snapshots before host admission.
+The batch callback receives the complete ordered frozen array of immutable
+`InvocationRequest` values for the Smith targets. Returning normally asserts
+that the host admitted that complete subset durably. Raising asserts that none
+of that subset was admitted: Smith dispatches no Smith tool and does not invoke
+the per-call failure handler. A host must therefore make callback return/raise
+agree with its own atomic transaction.
+
+Passing the provider collection and tool argument graph into this boundary
+transfers temporary ownership to Smith for the duration of capture. The provider
+and host must not mutate those containers concurrently. Smith admits native
+cardinality before copying and rejects a copy whose cardinality changed, but it
+deliberately does not freeze or otherwise mutate caller-owned containers.
+Sequential mutation after capture cannot alter the owned batch.
+
+Smith masks asynchronous interruption while the host admission callback runs and
+while its successful return is recorded in the local batch state; this prevents
+an interrupt from separating a committed host admission from Smith's dispatch
+decision. The callback must therefore be bounded and timeout-controlled. It
+should perform only the host's local atomic admission work, not provider I/O or
+an unbounded remote request.
+
+Configuring `batch_admitter` requires `failure_handler`. Smith rejects an
+admission callback without the corresponding terminal-failure callback before
+execution begins, so a host cannot opt into durable admission without also
+providing a way to terminate every admitted receipt.
+
+Unavailable calls and tools implemented directly as `RubyLLM::Tool` do not
+produce `InvocationRequest` values and are not covered by the host callback.
+They still consume the bounded allowance. A mixed batch can therefore be
+host-atomic only for its Smith-managed subset; hosts that require a durable
+receipt for every executable tool must bind only `Smith::Tool` adapters.
+
+After a callback returns, RubyLLM executes Smith's immutable admitted
+collection, not the caller-owned collection. Adding, removing, renaming, or
+mutating source calls after the snapshot therefore cannot alter the admitted
+execution. Smith still verifies that the exact registered tool object matches
+the admitted target. Each admitted call acquires one atomic dispatch claim;
+callback re-entry for the same admission is rejected before `perform` and cannot
+repeat its effect. The managed dispatch also owns a one-use execution authority.
+Calling a Smith tool directly from a provider callback or from another managed
+Smith tool fails closed; nested execution requires a future separately admitted
+invocation primitive. Tool replacement, a RubyLLM argument rejection, a callback
+failure before `Smith::Tool#perform`, or a Smith deadline that expires before
+`perform` raises `Smith::ToolDispatchRejected`. Smith attempts to notify every
+unsettled admitted sibling in one bounded pass even when one failure handler
+call raises. The callback must be idempotent because a failed notification
+remains unsettled for conservative host recovery. Errors from a failed terminal
+callback surface as `Smith::ToolFailureNotificationFailed` and are never
+transition-retryable. The error retains both the dispatch failure and the host
+callback failure.
+
+For an admitted provider-batch call, pre-execution hooks and tool guardrails
+receive an inspection-only argument Hash. The full admitted argument graph is
+Smith-owned and frozen, so policy inspection cannot rewrite the values that
+reach `perform`. Errors raised from inside `perform`, including
+`Smith::DeadlineExceeded`, do not prove that external work was absent and retain
+their original type. Process-fatal exceptions are never converted into receipt
+outcomes or terminal callbacks: an admitted receipt remains unresolved and the
+durable host must reconcile it before any resume decision. Smith never
+automatically replays that uncertain work. Failure-handler errors propagate
+because Smith cannot claim the host recorded a terminal outcome when it did not.
+
 You can still use RubyLLM agent tool wiring on your agents:
 
 ```ruby

data/lib/smith/agent/chat_construction.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module ChatConstruction
+      def chat(**kwargs)
+        kwargs, profile = prepare_input_kwargs(kwargs)
+
+        llm_chat = install_tool_execution_context(super)
+        normalize_chat(llm_chat, fallback_profile: profile)
+        llm_chat
+      end
+
+      def create(**kwargs)
+        kwargs, = prepare_input_kwargs(kwargs)
+        prepare_persisted_chat(super, kwargs:)
+      end
+
+      def create!(**kwargs)
+        kwargs, = prepare_input_kwargs(kwargs)
+        prepare_persisted_chat(super, kwargs:)
+      end
+
+      def find(id, **kwargs)
+        kwargs, = prepare_input_kwargs(kwargs)
+        prepare_persisted_chat(super, kwargs:)
+      end
+
+      private
+
+      def install_tool_execution_context(chat_object)
+        return unless chat_object
+
+        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+        Tool::ChatExecutionContext.install(llm_chat)
+        chat_object
+      end
+
+      def resolve_profile(model_id, provider: nil)
+        return unless model_id && defined?(Smith::Models)
+
+        Smith::Models.find_or_infer(model_id, provider: provider)
+      end
+
+      def prepare_persisted_chat(chat_object, kwargs:)
+        return unless chat_object
+
+        install_tool_execution_context(chat_object)
+        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+        profile = resolve_profile(
+          persisted_model_id(chat_object, kwargs),
+          provider: persisted_provider(chat_object, kwargs)
+        )
+        normalize_chat(llm_chat, fallback_profile: profile)
+        chat_object
+      end
+
+      def normalize_chat(llm_chat, fallback_profile:)
+        chat_model = llm_chat.model if llm_chat.respond_to?(:model)
+        profile = resolve_profile(
+          chat_model&.id || fallback_profile&.model_id,
+          provider: actual_provider(llm_chat) || fallback_profile&.provider
+        )
+        Smith::Models::Normalizer.apply!(llm_chat, profile: profile) if profile
+      end
+
+      def persisted_model_id(chat_object, kwargs)
+        kwargs[:model] || (chat_object.model_id if chat_object.respond_to?(:model_id)) || chat_kwargs[:model]
+      end
+
+      def persisted_provider(chat_object, kwargs)
+        kwargs[:provider] || (chat_object.provider if chat_object.respond_to?(:provider)) || configured_provider(kwargs)
+      end
+
+      def configured_provider(kwargs)
+        return kwargs[:provider] if kwargs.key?(:provider)
+        return if kwargs.key?(:model) && kwargs[:model].to_s != chat_kwargs[:model].to_s
+
+        chat_kwargs[:provider]
+      end
+
+      def actual_provider(llm_chat)
+        provider = llm_chat.instance_variable_get(:@provider)
+        provider.slug if provider.respond_to?(:slug)
+      end
+
+      def prepare_input_kwargs(kwargs)
+        model_id = kwargs[:model] || chat_kwargs[:model]
+        provider = configured_provider(kwargs)
+        profile = resolve_profile(model_id, provider:)
+        prepared = nil_fill_declared_inputs(inject_reserved_inputs(kwargs, profile, provider:))
+        [prepared, profile]
+      end
+
+      def inject_reserved_inputs(kwargs, profile, provider:)
+        return kwargs unless profile
+
+        {
+          model_id: profile.model_id,
+          provider:,
+          endpoint_mode: profile.endpoint_mode
+        }.merge(kwargs)
+      end
+
+      def nil_fill_declared_inputs(kwargs)
+        inputs.each_with_object(kwargs.dup) do |name, result|
+          result[name] = nil unless result.key?(name)
+        end
+      end
+    end
+  end
+end

data/lib/smith/agent/completion.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require_relative "../types"
+require_relative "provider_usage"
+
+module Smith
+  class Agent
+    class Completion < Dry::Struct
+      attribute :response, Types::Any
+      attribute :provider_usages, Types::Array.of(Types.Instance(ProviderUsage))
+      attribute :usage_complete, Types::Bool
+
+      def self.from_messages(response:, messages:)
+        assistant_messages = Array(messages).select do |message|
+          message.respond_to?(:role) && message.role.to_s == "assistant"
+        end
+        usage_source = assistant_messages.empty? ? [response] : assistant_messages
+
+        provider_usages = build_provider_usages(usage_source)
+        new(
+          response: response,
+          provider_usages:,
+          usage_complete: provider_usages.length == usage_source.length
+        )
+      end
+
+      def content
+        response.content if response.respond_to?(:content)
+      end
+
+      def input_tokens
+        provider_usages.sum(&:input_tokens) if usage_complete
+      end
+
+      def output_tokens
+        provider_usages.sum(&:output_tokens) if usage_complete
+      end
+
+      def self.build_provider_usages(messages)
+        messages.filter_map { |message| ProviderUsage.from_message(message) }.freeze
+      end
+      private_class_method :build_provider_usages
+    end
+  end
+end

data/lib/smith/agent/completion_usage_recording.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module CompletionUsageRecording
+      private
+
+      def record_completion_usage(agent_class, completion, attempt_kind, model_reference)
+        model_reference = coerce_model_reference(model_reference)
+        completion.provider_usages.each do |usage|
+          result = Workflow::AgentResult.new(
+            content: nil,
+            input_tokens: usage.input_tokens,
+            output_tokens: usage.output_tokens,
+            cost: nil,
+            model_used: model_reference.model_id,
+            provider_used: model_reference.provider
+          )
+          compute_agent_cost(result)
+          record_usage(agent_class, result, attempt_kind, model_reference)
+        end
+      end
+    end
+  end
+end

data/lib/smith/agent/dynamic_configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module DynamicConfiguration
+      attr_reader :model_block
+
+      def model(model_id = nil, **options, &block)
+        return configure_dynamic_model(model_id, options, block) if block
+
+        @model_block = nil
+        super
+      end
+
+      def model_configured?
+        !chat_kwargs[:model].nil? || !@model_block.nil?
+      end
+
+      def tools(*tools, &block)
+        return super unless block
+
+        super(&wrap_runtime_block(block))
+      end
+
+      def instructions(text = nil, **prompt_locals, &block)
+        return super unless block
+
+        super(text, **prompt_locals, &wrap_runtime_block(block))
+      end
+
+      def params(**params_kwargs, &block)
+        return super unless block
+
+        super(&wrap_runtime_block(block))
+      end
+
+      def headers(**headers_kwargs, &block)
+        return super unless block
+
+        super(&wrap_runtime_block(block))
+      end
+
+      def schema(value = nil, &block)
+        return super unless block
+
+        super(&wrap_runtime_block(block))
+      end
+
+      private
+
+      def configure_dynamic_model(model_id, options, block)
+        raise ArgumentError, "model can take a string id OR a block, not both" if model_id || options.any?
+
+        @model_block = block
+        @chat_kwargs ||= {}
+        @chat_kwargs.delete(:model)
+      end
+
+      def wrap_runtime_block(user_block)
+        return user_block if user_block.arity.zero?
+
+        proc do |*|
+          runtime = self
+          runtime.instance_exec(runtime, &user_block)
+        end
+      end
+    end
+  end
+end

data/lib/smith/agent/fallback_configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module FallbackConfiguration
+      def fallback_models(*models)
+        return @fallback_models_list if models.empty?
+
+        entries = models.flatten.compact.map { qualified_fallback_reference(_1) }
+        @fallback_models_list = entries.uniq(&:key).freeze
+      end
+
+      private
+
+      def qualified_fallback_reference(model)
+        reference = ModelReference.coerce(model)
+        return reference if reference.provider
+
+        raise Smith::WorkflowError,
+              "fallback model #{reference.model_id.inspect} must include an explicit provider"
+      rescue ArgumentError, Dry::Struct::Error => e
+        raise Smith::WorkflowError, "invalid fallback model: #{e.message}"
+      end
+    end
+  end
+end

data/lib/smith/agent/invocation_preparation.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module InvocationPreparation
+      WORKFLOW_CONTINUATION_MESSAGE =
+        "Use the preceding assistant result as input and perform your assigned workflow step."
+
+      private_constant :WORKFLOW_CONTINUATION_MESSAGE
+
+      private
+
+      def bridge_workflow_inputs(agent_class)
+        return {} unless @context.is_a?(Hash)
+
+        declared = agent_class.inputs || []
+        user_declared = declared - Smith::Agent::RESERVED_INPUT_NAMES
+        user_declared.to_h do |name|
+          [name, @context[name]]
+        end
+      end
+
+      def add_prepared_input(chat, prepared_input)
+        return unless prepared_input
+
+        prepared_input = provider_safe_prepared_input(prepared_input)
+        system_messages, other_messages = prepared_input.partition do |message|
+          message_role(message) == :system
+        end
+
+        merge_system_messages!(chat, system_messages) if system_messages.any?
+        other_messages.each { |message| add_message(chat, message) }
+      end
+
+      def provider_safe_prepared_input(prepared_input)
+        messages = prepared_input.to_a
+        return messages unless workflow_handoff?(messages)
+
+        messages + [{ role: :user, content: WORKFLOW_CONTINUATION_MESSAGE }]
+      end
+
+      def workflow_handoff?(messages)
+        message = messages.reverse_each.find { |candidate| message_role(candidate) != :system }
+        return false unless message
+        return false unless message_role(message) == :assistant
+        return false unless defined?(@last_output) && !@last_output.nil?
+
+        message_content(message) == @last_output
+      end
+
+      def merge_system_messages!(chat, prepared_system_messages)
+        return append_system_messages(chat, prepared_system_messages) unless chat.respond_to?(:messages)
+
+        combined_contents = existing_system_contents(chat) + prepared_system_contents(prepared_system_messages)
+        return if combined_contents.empty?
+        return append_system_messages(chat, prepared_system_messages) unless combined_contents.all?(String)
+
+        if chat.respond_to?(:with_instructions)
+          chat.with_instructions(combined_contents.join("\n\n"))
+        else
+          append_system_messages(chat, prepared_system_messages)
+        end
+      end
+
+      def append_system_messages(chat, messages)
+        messages.each { |message| add_message(chat, message) }
+      end
+
+      def existing_system_contents(chat)
+        chat.messages.filter_map do |message|
+          message.content if message_role(message) == :system
+        end
+      end
+
+      def prepared_system_contents(messages)
+        messages.filter_map { |message| message_content(message) }
+      end
+
+      def add_message(chat, message)
+        attributes = if message.is_a?(Hash)
+                       message.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+                     else
+                       message
+                     end
+        chat.add_message(attributes)
+      end
+
+      def message_role(message)
+        message_attribute(message, :role)&.to_sym
+      end
+
+      def message_content(message)
+        message_attribute(message, :content)
+      end
+
+      def message_attribute(message, name)
+        return message.public_send(name) if message.respond_to?(name)
+        return message[name] if message.respond_to?(:key?) && message.key?(name)
+
+        message[name.to_s]
+      end
+    end
+  end
+end