smith-agents 0.7.0 → 0.10.0

data/lib/smith/agent/invocation_preparation.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+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
+        attributes = provider_safe_message(attributes) if attributes.is_a?(Hash)
+        chat.add_message(attributes)
+      end
+
+      # A structured agent output recorded as a session message (StepCompletion#append_accepted_output)
+      # carries a Hash/Array content. RubyLLM's Message#normalize_content treats a Hash content as
+      # { text:, ...attachments } and opens each value as a file, so replaying a prior structured
+      # output to the next agent in a workflow session raises Errno::ENOENT. Serialize non-string
+      # content to JSON so the provider sees the prior output as text; the session store keeps the raw
+      # value (last_output stays structured), only this provider-facing copy is serialized. Genuine
+      # multimodal attachments are supplied through the provider's own with: mechanism, never as a bare
+      # Hash message content in a workflow session.
+      def provider_safe_message(attributes)
+        content = attributes[:content]
+        return attributes if content.nil? || content.is_a?(String)
+
+        attributes.merge(content: json_message_content(content))
+      end
+
+      def json_message_content(content)
+        JSON.generate(content)
+      rescue StandardError
+        content.to_s
+      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

data/lib/smith/agent/lifecycle.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "provider_completion"
+require_relative "usage_tracking"
+
 module Smith
   class Agent
     module Lifecycle
-      WORKFLOW_CONTINUATION_MESSAGE =
-        "Use the preceding assistant result as input and perform your assigned workflow step."
-      private_constant :WORKFLOW_CONTINUATION_MESSAGE
-
-      TRANSIENT_ERRORS = [
-        RubyLLM::ServerError, RubyLLM::ServiceUnavailableError,
-        RubyLLM::OverloadedError, RubyLLM::RateLimitError
-      ].freeze
+      include ProviderCompletion
+      include UsageTracking
 
       private
 
@@ -23,275 +20,11 @@ module Smith
 
       def invoke_agent(agent_class, prepared_input, output_schema: agent_class.output_schema)
         check_deadline!
-        response, model_used = complete_with_provider(agent_class, prepared_input, output_schema:)
-        snapshot_and_finalize(agent_class, response, model_used)
-      end
-
-      # Returns [response, model_used] as local data — no shared mutable
-      # state. Previously this method set `@last_attempt_model` on the
-      # workflow instance and `snapshot_and_finalize` read it back; under
-      # parallel fan-out, two branches sharing the workflow could race
-      # and attribute the wrong model to the wrong response. Local data
-      # eliminates the race entirely.
-      def complete_with_provider(agent_class, prepared_input, output_schema:)
-        models = build_model_chain(agent_class)
-
-        models.each_with_index do |model_id, index|
-          check_deadline! if index.positive?
-          response = attempt_model(agent_class, prepared_input, model_id, output_schema:)
-          return [response, model_id]
-        rescue Smith::Error
-          raise
-        rescue StandardError => e
-          account_failed_attempt(e, model_id, agent_class)
-          raise Smith::AgentError, e.message unless fallback_eligible?(e) && index < models.length - 1
-        end
-      end
-
-      def build_model_chain(agent_class)
-        primary = if agent_class.respond_to?(:model_block) && agent_class.model_block
-                    resolve_dynamic_model(agent_class)
-                  else
-                    agent_class.chat_kwargs[:model]
-                  end
-        fallbacks = agent_class.fallback_models || []
-        [primary, *fallbacks].compact
-      end
-
-      # Evaluates a block-form `model` declaration with the workflow's
-      # @context (Hash, defaults to {} when uninitialized). The block
-      # must return a non-empty string model id; any other value
-      # surfaces as Smith::AgentError so the workflow's failure handler
-      # treats it as a step failure rather than a silent miss.
-      def resolve_dynamic_model(agent_class)
-        result = agent_class.model_block.call(@context || {})
-        return result if result.is_a?(String) && !result.empty?
-
-        raise Smith::AgentError,
-              "model block for #{agent_class} must return a non-empty string; got #{result.inspect}"
-      end
-
-      def attempt_model(agent_class, prepared_input, model_id, output_schema:)
-        chat = agent_class.chat(model: model_id, **bridge_workflow_inputs(agent_class))
-        add_prepared_input(chat, prepared_input)
-        chat = chat.with_schema(output_schema) if output_schema
-        chat.complete
-      end
-
-      # Bridges declared agent `inputs` from the workflow's @context Hash
-      # to the agent invocation kwargs, so block-form RubyLLM DSLs (tools,
-      # instructions, params, headers, schema) can access workflow-context
-      # data via bare method calls on `self` inside the block (RubyLLM
-      # invokes these via `runtime.instance_exec(&block)`, exposing each
-      # declared input as a singleton method on the runtime object).
-      # Smith's own `model` block-form already receives @context directly
-      # via `block.call(@context)`; this bridge gives runtime_context the
-      # same surface for the RubyLLM-owned blocks.
-      #
-      # Bridges ONLY user-declared inputs — reserved names
-      # (Smith::Agent::RESERVED_INPUT_NAMES: model_id, provider,
-      # endpoint_mode) are auto-injected by Smith::Agent.chat from the
-      # resolved profile, NOT from @context. The slice prevents the bridge
-      # from accidentally passing through stale or wrong values that
-      # happen to live in @context under those keys.
-      #
-      # Contract: declared inputs are ALWAYS passed (with nil when absent
-      # from @context). The declaration is the contract — `inputs :form_kind`
-      # promises that `form_kind` will be a callable singleton method on
-      # the runtime regardless of whether @context happens to have a value.
-      # This eliminates `respond_to?` defensiveness in agent blocks and
-      # mirrors the silent-nil semantics agent authors get from `ctx[:k]`
-      # in the model block. Non-Hash @context short-circuits.
-      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 prepared_system_messages.each { |message| add_message(chat, message) } unless chat.respond_to?(:messages)
-
-        existing_system_contents = chat.messages.filter_map do |message|
-          message.content if message_role(message) == :system
-        end
-        prepared_system_contents = prepared_system_messages.filter_map do |message|
-          message_content(message)
-        end
-
-        combined_contents = existing_system_contents + prepared_system_contents
-        return if combined_contents.empty?
-        unless combined_contents.all?(String)
-          return prepared_system_messages.each { |message| add_message(chat, message) }
-        end
-
-        if chat.respond_to?(:with_instructions)
-          chat.with_instructions(combined_contents.join("\n\n"))
-        else
-          prepared_system_messages.each { |message| add_message(chat, message) }
-        end
-      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
-
-      def fallback_eligible?(error)
-        TRANSIENT_ERRORS.any? { |klass| error.is_a?(klass) } ||
-          error.is_a?(Faraday::TimeoutError) ||
-          error.is_a?(Faraday::ConnectionFailed)
-      end
-
-      # `agent_class` is now a parameter (was previously implicit via
-      # `@last_attempt_model`-only path). The caller (`complete_with_provider`)
-      # has the local already, so no shared mutable state is needed.
-      # Records the failed attempt's tokens via the unified `record_usage`
-      # helper, marking the entry as `:failed_attempt`.
-      def account_failed_attempt(error, model_id, agent_class)
-        return unless error.respond_to?(:input_tokens) && error.respond_to?(:output_tokens)
-
-        input = error.input_tokens
-        output = error.output_tokens
-        return unless input.is_a?(Integer) && output.is_a?(Integer)
-
-        cost = Smith::Pricing.compute_cost(model: model_id, input_tokens: input, output_tokens: output)
-        agent_result = Workflow::AgentResult.new(
-          content: nil, input_tokens: input, output_tokens: output, cost: cost, model_used: model_id
-        )
-        Thread.current[:smith_failed_agent_results] ||= []
-        Thread.current[:smith_failed_agent_results] << agent_result
-        record_usage(agent_class, agent_result, :failed_attempt, model_id)
-      end
-
-      def snapshot_and_finalize(agent_class, response, model_used)
-        agent_result = Workflow::AgentResult.from_response(response, response&.content, model_used: model_used)
-        Thread.current[:smith_last_agent_result] = agent_result
-        emit_token_usage(agent_result)
-        compute_agent_cost(agent_result)
-        record_usage(agent_class, agent_result, :completed_attempt, agent_result.model_used)
-
-        agent_result.content = run_after_completion(agent_class, agent_result.content, @context)
-        raise_blank_output!(agent_class, agent_result)
-        agent_result
-      end
-
-      def raise_blank_output!(agent_class, agent_result)
-        return unless blank_agent_output?(agent_result.content)
-
-        raise Smith::BlankAgentOutputError.new(
-          agent_name: agent_class.register_as,
-          model_used: agent_result.model_used
+        attempt = complete_with_provider(agent_class, prepared_input, output_schema:)
+        snapshot_and_finalize(
+          agent_class, attempt.completion, attempt.model_reference, attempt_id: attempt.attempt_id
         )
       end
-
-      def blank_agent_output?(content)
-        return true if content.nil?
-        return content.strip.empty? if content.is_a?(String)
-
-        false
-      end
-
-      def emit_token_usage(agent_result)
-        return unless agent_result.usage_known?
-
-        Smith::Trace.record(
-          type: :token_usage,
-          data: { input_tokens: agent_result.input_tokens, output_tokens: agent_result.output_tokens }
-        )
-      end
-
-      def compute_agent_cost(agent_result)
-        return unless agent_result.usage_known?
-
-        model = agent_result.model_used
-        agent_result.cost = Smith::Pricing.compute_cost(
-          model: model, input_tokens: agent_result.input_tokens, output_tokens: agent_result.output_tokens
-        )
-      end
-
-      # Single critical section: all three of `@total_tokens`,
-      # `@total_cost`, and `@usage_entries` update under one mutex
-      # acquisition. Replaces the prior `accumulate_usage` which took
-      # the mutex twice (once for tokens, once for cost) — under
-      # parallel fan-out two branches could interleave between those
-      # blocks, leaving totals momentarily inconsistent. Adding the
-      # entry append in a third pass would have widened the window;
-      # one pass closes it entirely.
-      #
-      # `@usage_mutex` is eagerly initialized in `Workflow#initialize`
-      # AND `Workflow#restore_state` (since `from_state` allocates
-      # without `initialize`), so it's always present here.
-      def record_usage(agent_class, agent_result, attempt_kind, model_id)
-        return unless agent_result.usage_known?
-
-        entry = Workflow::UsageEntry.new(
-          usage_id: SecureRandom.uuid,
-          agent_name: agent_class.register_as,
-          model: model_id,
-          input_tokens: agent_result.input_tokens,
-          output_tokens: agent_result.output_tokens,
-          cost: agent_result.cost,
-          attempt_kind: attempt_kind,
-          recorded_at: Time.now.utc.iso8601
-        )
-
-        @usage_mutex.synchronize do
-          @total_tokens = (@total_tokens || 0) + agent_result.input_tokens + agent_result.output_tokens
-          @total_cost   = (@total_cost   || 0.0) + (agent_result.cost || 0.0)
-          @usage_entries << entry
-        end
-      end
     end
   end
 end

data/lib/smith/agent/model_reference.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "ruby_llm"
+
+require_relative "../types"
+
+module Smith
+  class Agent < RubyLLM::Agent
+    class ModelReference < Dry::Struct
+      ModelId = Types::String.constructor do |value|
+        normalized = value.to_s.dup
+        raise ArgumentError, "model id must not be blank" if normalized.empty?
+
+        normalized.freeze
+      end
+      Provider = Types::Symbol.optional.constructor { |value| value&.to_sym }
+
+      private_constant :ModelId, :Provider
+
+      attribute :model_id, ModelId
+      attribute :provider, Provider
+
+      def initialize(attributes)
+        super
+        freeze
+      end
+
+      def self.coerce(value, provider: nil)
+        return value if value.is_a?(self)
+        return from_hash(value) if value.is_a?(Hash)
+        return parse(value) if provider.nil? && value.is_a?(String) && value.include?("/")
+
+        new(model_id: value, provider:)
+      end
+
+      def self.from_hash(value)
+        attributes = value.transform_keys(&:to_sym)
+        new(model_id: attributes[:model_id] || attributes[:model], provider: attributes[:provider])
+      end
+      private_class_method :from_hash
+
+      # Inverse of #to_s: the first slash separates provider from model,
+      # so a reference whose model id itself contains slashes round-trips
+      # ("openrouter/openai/gpt-5" -> provider :openrouter,
+      # model "openai/gpt-5"). An explicit `provider:` keyword keeps the
+      # string literal and is never re-split.
+      def self.parse(value)
+        provider, model_id = value.split("/", 2)
+        raise ArgumentError, "provider segment in #{value.inspect} must not be blank" if provider.empty?
+
+        new(model_id:, provider:)
+      end
+
+      def key
+        [provider, model_id].freeze
+      end
+
+      # True when the two references can address the same physical model:
+      # an unqualified reference delegates provider selection to RubyLLM,
+      # so it can resolve to any provider serving the same model id.
+      def same_candidate?(other)
+        model_id == other.model_id &&
+          (provider.nil? || other.provider.nil? || provider == other.provider)
+      end
+
+      def chat_options
+        { model: model_id, provider: }.compact.freeze
+      end
+
+      def to_s
+        provider ? "#{provider}/#{model_id}" : model_id
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_attempt.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+require_relative "model_reference"
+
+module Smith
+  class Agent
+    class ProviderAttempt < Dry::Struct
+      attribute :completion, Types::Any.optional
+      attribute :model_reference, Types.Instance(ModelReference)
+      attribute :error, Types.Instance(StandardError).optional
+      # One attempt = one chat completion (including any provider tool loop).
+      # `attempt_id` joins the attempt's usage entries to its single measured
+      # duration; `duration_ms` is nil when the attempt failed before the
+      # completion call started.
+      attribute :attempt_id, Types::String.optional.default(nil)
+      attribute :duration_ms, Types::Integer.optional.default(nil)
+
+      def self.success(completion:, model_reference:, attempt_id: nil, duration_ms: nil)
+        new(completion:, model_reference:, error: nil, attempt_id:, duration_ms:)
+      end
+
+      def self.failure(error:, model_reference:, attempt_id: nil, duration_ms: nil)
+        new(completion: nil, model_reference:, error:, attempt_id:, duration_ms:)
+      end
+
+      def success?
+        error.nil?
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_call_timing.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    # Monotonic timing and trace emission for one provider attempt: the
+    # attempt's single measured duration wraps the whole chat completion
+    # (including any provider-side tool loop). Per-network-round timing
+    # belongs to the host's RubyLLM notification subscriptions, not Smith.
+    module ProviderCallTiming
+      class Timer
+        def self.start
+          new
+        end
+
+        def initialize
+          @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @stopped_at = nil
+        end
+
+        # Idempotent: the first stop wins, so a rescue-path stop after a
+        # success-path stop cannot stretch the measurement.
+        def stop
+          @stopped_at ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          self
+        end
+
+        def elapsed_ms
+          ending = @stopped_at || Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ((ending - @started_at) * 1000).round
+        end
+      end
+
+      private
+
+      # One `:provider_call` trace per attempt: success, provider failure, or
+      # aborted (a non-provider error that re-raises). Usage entries from the
+      # same attempt share its attempt_id; join there instead of summing
+      # durations across entries. duration_ms is present only when the timed
+      # provider call actually started: a failure before dispatch (model
+      # resolution, chat construction) emits its attempt without a duration.
+      def record_provider_call_trace(attempt, attempt_index, aborted: false)
+        Smith::Trace.record(
+          type: :provider_call,
+          data: {
+            model: attempt.model_reference.model_id,
+            provider: attempt.model_reference.provider,
+            duration_ms: attempt.duration_ms,
+            attempt_id: attempt.attempt_id,
+            attempt_index: attempt_index,
+            outcome: provider_call_outcome(attempt, aborted)
+          }.compact
+        )
+      end
+
+      def provider_call_outcome(attempt, aborted)
+        return :aborted if aborted
+        return :success if attempt.success?
+
+        :failure
+      end
+
+      # Aborted (non-provider) attempts emit a :provider_call too, so the
+      # prefix-accounted usage entries stamped with this attempt_id always
+      # have their join target; the error then propagates unchanged.
+      def failed_provider_attempt(error, observed_reference, attempt_id, timer, attempt_index)
+        attempt = ProviderAttempt.failure(
+          error: error, model_reference: observed_reference, attempt_id:, duration_ms: timer&.elapsed_ms
+        )
+        record_provider_call_trace(attempt, attempt_index, aborted: !provider_failure?(error))
+        attempt
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_candidate_sequence.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    class ProviderCandidateSequence
+      include Enumerable
+
+      def initialize(references)
+        @references = references.freeze
+        @remaining_by_provider = references.each_with_object(Hash.new(0)) do |reference, counts|
+          counts[reference.provider] += 1
+        end
+        @unavailable_providers = {}
+        @available_count = references.length
+      end
+
+      # Returns self so an exhausted sequence can never be mistaken for
+      # an attempt result by a caller that forgets to fail closed.
+      def each
+        return enum_for(:each) unless block_given?
+
+        references.each_with_index do |reference, index|
+          consume(reference)
+          yield reference, index unless unavailable?(reference.provider)
+        end
+        self
+      end
+
+      def suppress(provider)
+        return unless provider
+        return if unavailable?(provider)
+
+        unavailable_providers[provider] = true
+        @available_count -= remaining_by_provider.fetch(provider, 0)
+      end
+
+      def fallback_available?
+        @available_count.positive?
+      end
+
+      private
+
+      attr_reader :references, :remaining_by_provider, :unavailable_providers
+
+      def consume(reference)
+        remaining_by_provider[reference.provider] -= 1
+        @available_count -= 1 unless unavailable?(reference.provider)
+      end
+
+      def unavailable?(provider)
+        unavailable_providers.key?(provider)
+      end
+    end
+  end
+end