activeagent 1.8.1 → 1.9.0

data/lib/active_agent/providers/ruby_llm_provider.rb

@@ -42,7 +42,7 @@ module ActiveAgent
       # provider.complete().
       #
       # @param parameters [Hash] serialized request parameters
-      # @return [Hash, nil] normalized API response hash, or nil for streaming
+      # @return [Hash] normalized API response, or metadata for a streamed turn
       def api_prompt_execute(parameters)
         @resolved_model_id = parameters[:model] || options.model
         resolve_ruby_llm_provider!(@resolved_model_id)
@@ -72,16 +72,24 @@ module ActiveAgent
           end
         end
 
+        # Blank means unset, as from an ERB value whose variable is unset.
+        if (protocol = options.protocol.presence)
+          raise ArgumentError, "The protocol option needs ruby_llm 2.0 or newer, and #{::RubyLLM::VERSION} is loaded" unless ruby_llm_v2?
+
+          kwargs[:protocol] = protocol.to_sym
+        end
+
         if parameters[:stream]
           stream_proc = parameters[:stream]
           @stream_tool_calls = {}
+          @stream_response = { model: @resolved_model_id, stop_reason: "end_turn" }
 
           # For streaming, pass a block that forwards chunks
           @ruby_llm_provider.complete(messages, **kwargs) do |chunk|
             stream_proc.call(chunk)
           end
 
-          nil
+          @stream_response
         else
           response = @ruby_llm_provider.complete(messages, **kwargs)
           normalize_ruby_llm_response(response, @resolved_model_id)
@@ -145,37 +153,63 @@ module ActiveAgent
         if chunk.tool_calls&.any?
           message[:tool_calls] ||= []
           chunk.tool_calls.each do |key, tool_call|
-            # RubyLLM 2 keys OpenAI deltas by index; only the first delta
-            # includes the call ID and name. Keep each index tied to its call.
-            existing = message[:tool_calls].find { |tc| tool_call.id && tc[:id] == tool_call.id }
-            existing ||= @stream_tool_calls[key]
+            # Only the first delta of a call has its ID and name; the rest
+            # are fragments of its arguments. A fragment belongs to the call
+            # that shares its stream key (the index RubyLLM 2 numbers calls
+            # by), or, without one as RubyLLM 1.16 leaves it for OpenAI, to
+            # the latest call. RubyLLM 1.16 cannot preserve interleaved
+            # OpenAI calls: its parser drops their indices and fragments.
+            existing = if tool_call.id
+              message[:tool_calls].find { |tc| tc[:id] == tool_call.id }
+            else
+              @stream_tool_calls[key] || message[:tool_calls].last
+            end
+            fragment = streamed_tool_arguments(tool_call.arguments)
             if existing
-              existing[:function][:arguments] += tool_call.arguments.to_s if tool_call.arguments
+              existing[:function][:arguments] += fragment
             else
               existing = {
                 id: tool_call.id,
                 type: "function",
                 function: {
                   name: tool_call.name,
-                  arguments: tool_call.arguments.to_s
+                  arguments: fragment
                 }
               }
               message[:tool_calls] << existing
             end
-            @stream_tool_calls[key] = existing
+            @stream_tool_calls[key] = existing unless key.nil?
           end
         end
 
-        # Stream completion is handled by the base provider after
-        # api_prompt_execute returns nil. No action needed here.
+        # Counts arrive in separate chunks (Anthropic sends input at the start
+        # and output at the end). They are cumulative for this turn, so merge
+        # reported fields rather than adding each chunk's counts.
+        if (usage = ruby_llm_usage(chunk))
+          (@stream_response[:usage] ||= {}).merge!(usage) do |field, previous, current|
+            # Chat Completions synthesizes zero when cache writes are omitted.
+            # That cannot erase writes already counted in this turn.
+            field == :cache_creation_tokens && current == 0 ? previous : current
+          end
+        end
+        if chunk.respond_to?(:finish_reason) && chunk.finish_reason
+          @stream_response[:stop_reason] = ruby_llm_stop_reason(chunk, tool_calls: message[:tool_calls])
+        elsif message[:tool_calls]&.any? && @stream_response[:stop_reason] == "end_turn"
+          @stream_response[:stop_reason] = "tool_use"
+        end
+
+        # The base provider finishes the turn after api_prompt_execute returns
+        # its metadata, once every chunk has been consumed.
       end
 
       # Extracts messages from the completed API response.
       #
-      # @param api_response [Hash, nil] normalized response hash
+      # @param api_response [Hash, nil] normalized response or stream metadata
       # @return [Array<Hash>, nil]
       def process_prompt_finished_extract_messages(api_response)
         return nil unless api_response
+        return nil if request.stream
+
         [ api_response ]
       end
 
@@ -241,16 +275,20 @@ module ActiveAgent
         end
       end
 
-      # Executes tool calls and pushes results to message_stack.
+      # Executes tool calls and pushes results to message_stack. Pushes
+      # nothing when a call paused for the user.
       #
       # @param tool_calls [Array<Hash>] with :id, :name, :input keys
       # @return [void]
       def process_function_calls(tool_calls)
-        tool_calls.each do |tool_call|
-          content = instrument("tool_call.active_agent", tool_name: tool_call[:name]) do
-            tools_function.call(tool_call[:name], **tool_call[:input])
+        results = dispatch_tool_calls(tool_calls) do |tool_call|
+          instrument("tool_call.active_agent", tool_name: tool_call[:name]) do
+            call_tool_function(tool_call[:name], **tool_call[:input])
           end
+        end
+        return unless results
 
+        tool_calls.zip(results).each do |tool_call, content|
           message_stack.push({
             role: "tool",
             tool_call_id: tool_call[:id],
@@ -259,7 +297,8 @@ module ActiveAgent
         end
       end
 
-      # api_prompt_execute always returns a normalized Hash or nil (streaming),
+      # api_prompt_execute always returns a normalized Hash (stream metadata
+      # carries the final usage and stop reason without another message),
       # so no additional normalization is needed for instrumentation.
       # Inherits default api_response_normalize from BaseProvider.
 
@@ -393,6 +432,10 @@ module ActiveAgent
       # complete takes, { name:, schema:, strict: }, filling the name and
       # strict flag in the way RubyLLM::Chat#with_schema does.
       #
+      # A json_schema takes its name, schema and strict flag nested under
+      # +json_schema+ or beside +type+, the two shapes the OpenAI providers
+      # accept; a field given beside +type+ wins, as it does there.
+      #
       # @param response_format [Hash, Symbol, String, nil] ActiveAgent common format
       # @return [Hash, nil] nil when the response is plain text
       # @raise [ArgumentError] for json_schema without a schema, and for any
@@ -406,10 +449,12 @@ module ActiveAgent
         when "text"
           nil
         when "json_schema"
-          json_schema = format[:json_schema] || {}
-          raise ArgumentError, "RubyLLMProvider needs a schema for a json_schema response_format" unless json_schema[:schema]
+          nested = format[:json_schema] || {}
+          schema = format[:schema] || nested[:schema]
+          raise ArgumentError, "RubyLLMProvider needs a schema for a json_schema response_format" unless schema
 
-          { name: json_schema[:name] || "response", schema: json_schema[:schema], strict: json_schema[:strict] != false }
+          strict = format.fetch(:strict) { nested[:strict] }
+          { name: format[:name] || nested[:name] || "response", schema: schema, strict: strict != false }
         else
           raise ArgumentError, "RubyLLMProvider supports a json_schema or text response_format, not #{format[:type].inspect}; " \
                                "ruby_llm has no JSON object mode, so give json_schema a schema instead"
@@ -463,27 +508,80 @@ module ActiveAgent
         if response.respond_to?(:stop_reason) && response.stop_reason
           hash[:stop_reason] = response.stop_reason
         elsif response.respond_to?(:finish_reason) && response.finish_reason
-          hash[:stop_reason] = { stop: "end_turn", tool_calls: "tool_use" }.fetch(response.finish_reason, response.finish_reason.to_s)
+          hash[:stop_reason] = ruby_llm_stop_reason(response)
         elsif response.tool_calls&.any?
           hash[:stop_reason] = "tool_use"
         else
           hash[:stop_reason] = "end_turn"
         end
 
-        # Add usage info if available
+        usage = ruby_llm_usage(response)
+        hash[:usage] = usage if usage
+
+        hash[:model] = model_id if model_id
+
+        hash
+      end
+
+      # A streamed tool call's arguments as the text they add to the JSON
+      # string the call builds up. Most APIs stream that string; Anthropic
+      # opens a call with an empty Hash for its input, and Gemini sends the
+      # arguments whole as a Hash.
+      #
+      # @param arguments [String, Hash, nil]
+      # @return [String]
+      def streamed_tool_arguments(arguments)
+        case arguments
+        when String then arguments
+        when Hash then arguments.empty? ? "" : arguments.to_json
+        else ""
+        end
+      end
+
+      # ruby_llm's normalized finish reason as the stop reason ActiveAgent
+      # reports. A response that asks for tools is tool_use however the API
+      # ends it: OpenAI's Responses API ends one with :stop. A reason
+      # ActiveAgent has no name for, such as Anthropic's :pause_turn, is kept
+      # as the provider spelled it.
+      #
+      # @param response [RubyLLM::Message] carrying a finish_reason
+      # @return [String]
+      def ruby_llm_stop_reason(response, tool_calls: response.tool_calls)
+        return "tool_use" if response.finish_reason == :stop && tool_calls&.any?
+
+        { stop: "end_turn", tool_calls: "tool_use" }.fetch(response.finish_reason, response.finish_reason.to_s)
+      end
+
+      # The tokens ruby_llm counted for the response, or nil when it counted
+      # none: the message has no Tokens then in ruby_llm 1.x. RubyLLM counts
+      # cached tokens apart from the input, so input_tokens leaves them out.
+      # A count the provider left out is left out here too, and Usage reads it
+      # as zero.
+      #
+      # @param response [RubyLLM::Message]
+      # @return [Hash, nil] Common::Usage attributes
+      def ruby_llm_usage(response)
         if response.respond_to?(:tokens)
           tokens = response.tokens
-          hash[:usage] = { input_tokens: tokens.input, output_tokens: tokens.output } if tokens.input
+          return unless tokens
+
+          usage = {
+            input_tokens: tokens.input,
+            output_tokens: tokens.output,
+            cached_tokens: tokens.cache_read,
+            cache_creation_tokens: tokens.cache_write,
+            reasoning_tokens: tokens.thinking
+          }.compact
+          # ruby_llm's OpenAI parser reports cache_write: 0 for a response or
+          # chunk that carries no usage at all, so a zero cache or thinking
+          # count is not a count. Input and output are, even at zero.
+          usage if usage[:input_tokens] || usage[:output_tokens] || usage.values.any?(&:positive?)
         elsif response.respond_to?(:input_tokens) && response.input_tokens
-          hash[:usage] = {
+          {
             input_tokens: response.input_tokens,
             output_tokens: response.output_tokens
-          }
+          }.compact
         end
-
-        hash[:model] = model_id if model_id
-
-        hash
       end
     end
   end

data/lib/active_agent/schema_tools.rb

@@ -83,6 +83,18 @@ module ActiveAgent
       "on_or_before" => :lteq, "on_or_after" => :gteq
     }.freeze
 
+    # Column names that look like they hold a credential. The schema tools
+    # generator never suggests one, and the dashboard never lets one be
+    # chosen: reading one back would hand a model a credential, and
+    # filtering on one leaks it a character at a time through the row
+    # counts.
+    SECRET_COLUMNS = /password|digest|token|secret|api_key|otp|encrypted|ssn/i
+
+    # Heads a file `active_agent:schema_tools --managed` wrote. The
+    # dashboard rewrites and removes only tools files that carry it, so
+    # deleting the line hands the file back to whoever edits it.
+    MANAGED_MARKER = "Managed by the ActiveAgent dashboard"
+
     # Raised when a tool call names a column outside the declared allowlists,
     # or is otherwise outside the declared boundary.
     class UnpermittedAttribute < ArgumentError; end

data/lib/active_agent/telemetry/instrumentation.rb

@@ -212,6 +212,7 @@ module ActiveAgent
               if result.respond_to?(:finish_reason) && result.finish_reason.present?
                 llm_span.set_attribute("llm.finish_reason", result.finish_reason.to_s)
               end
+              span.set_attribute("agent.awaiting_input", true) if result.try(:awaiting_input?)
 
               llm_span.set_status(:ok)
               llm_span.finish
@@ -254,7 +255,10 @@ module ActiveAgent
             capture_bodies = agent.send(:telemetry_capture_bodies?)
             arguments = kwargs.presence || (args.length == 1 ? args.first : args.presence)
             if arguments.present? && capture_bodies
-              tool_span.set_attribute("tool.input.args", agent.send(:telemetry_truncate, JSON.generate(arguments)))
+              # The result and any error arrive from `base` with secret
+              # answers already scrubbed; the arguments have not been through it.
+              recorded = agent.send(:telemetry_scrub_secrets, JSON.generate(arguments))
+              tool_span.set_attribute("tool.input.args", agent.send(:telemetry_truncate, recorded))
             end
             begin
               result = base.call(tool_name, *args, **kwargs)
@@ -338,6 +342,11 @@ module ActiveAgent
           nil
         end
 
+        # @return [String] `text` without the generation's secret answers
+        def telemetry_scrub_secrets(text)
+          respond_to?(:scrub_input_request_secrets, true) ? scrub_input_request_secrets(text) : text
+        end
+
         def telemetry_truncate(value)
           text = value.to_s
           return text if text.length <= TELEMETRY_ATTRIBUTE_MAX_CHARS

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.8.1"
+  VERSION = "1.9.0"
 end

data/lib/active_agent.rb

@@ -100,6 +100,8 @@ module ActiveAgent
   autoload :Streaming, "active_agent/concerns/streaming"
   autoload :InlinePreviewInterceptor
   autoload :Generation
+  autoload :InputRequest
+  autoload :InputRequests, "active_agent/concerns/input_requests"
   autoload :Queueing, "active_agent/concerns/queueing"
   autoload :Parameterized, "active_agent/concerns/parameterized"
   autoload :Preview, "active_agent/concerns/preview"

data/lib/generators/active_agent/schema_tools/USAGE

@@ -20,3 +20,14 @@ Examples:
 
     scopes reads through ReservationPolicy::Scope even if it cannot be
     found from here.
+
+    `bin/rails generate active_agent:schema_tools Reservation --filterable status --returns status starts_at`
+
+    declares exactly those columns (after `id`) instead of suggesting them.
+    A column that looks like a secret, or that the model does not have, is
+    left out.
+
+    `bin/rails generate active_agent:schema_tools Reservation --managed --returns status`
+
+    heads the file with a comment saying the ActiveAgent dashboard manages
+    it: a project's boots rewrite or remove only files that carry it.

data/lib/generators/active_agent/schema_tools/schema_tools_generator.rb

@@ -11,16 +11,25 @@ module ActiveAgent
     # a judgement about exposure, not a fact about the table (#440). Every
     # column the model has is listed, commented out, minus the ones that look
     # like secrets, so the allowlist is a review step rather than a blank page.
+    #
+    # --filterable and --returns write that review's outcome instead: the
+    # columns named are declared, and only those. --managed heads the file
+    # with ActiveAgent::SchemaTools::MANAGED_MARKER, which a dashboard
+    # project's boots look for before they rewrite or remove it.
     class SchemaToolsGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
-      # Columns never suggested, whatever the model: reading one back would
-      # hand a model a credential, and filtering on one leaks it a character
-      # at a time through the row counts.
-      SECRET_COLUMNS = /password|digest|token|secret|api_key|otp|encrypted|ssn/i
+      # Columns never suggested or written, whatever the model.
+      SECRET_COLUMNS = ActiveAgent::SchemaTools::SECRET_COLUMNS
 
       class_option :policy, type: :boolean, default: nil,
         desc: "Scope every read through <Model>Policy::Scope (default: when that policy exists)"
+      class_option :filterable, type: :array, default: nil,
+        desc: "Columns an agent may filter on, declared rather than suggested"
+      class_option :returns, type: :array, default: nil,
+        desc: "Columns an agent may read back, declared rather than suggested"
+      class_option :managed, type: :boolean, default: false,
+        desc: "Head the file with ActiveAgent::SchemaTools::MANAGED_MARKER, for a dashboard project that rewrites it"
 
       check_class_collision suffix: "Tools"
 
@@ -68,6 +77,32 @@ module ActiveAgent
         columns.reject { |name, _type| name == "id" || name.match?(SECRET_COLUMNS) }
       end
 
+      # The columns --filterable or --returns (+option+) declares, after +id+:
+      # nil when the option is not given. A column that looks like a secret,
+      # or that the model's table does not have when it can be read, is
+      # left out with a note.
+      def declared_columns(option)
+        names = options[option]
+        return nil if names.nil?
+
+        known = columns.map(&:first)
+        names.map(&:to_s).uniq.reject { |name| name == "id" }.select do |name|
+          if name.match?(SECRET_COLUMNS)
+            say_status :skip, "#{name}: looks like a secret, so it is not declared", :yellow
+            false
+          elsif known.any? && !known.include?(name)
+            say_status :skip, "#{name}: #{class_name} has no such column", :yellow
+            false
+          else
+            true
+          end
+        end
+      end
+
+      def column_list(names)
+        [ "id", *names ].map { |name| ":#{name}" }.join(", ")
+      end
+
       def secret_columns
         columns.select { |name, _type| name.match?(SECRET_COLUMNS) }.map(&:first)
       end

data/lib/generators/active_agent/schema_tools/templates/schema_tools.rb.tt

@@ -1,4 +1,9 @@
 <% module_namespacing do -%>
+<% if options[:managed] -%>
+# <%= ActiveAgent::SchemaTools::MANAGED_MARKER %>: a project's choice of what its
+# App assistant may read rewrites or removes this file on every boot. Delete
+# these three lines to keep your own edits.
+<% end -%>
 # Bounded, read-only agent tools over <%= class_name %>:
 # find_<%= collection_name %>, count_<%= collection_name %>, get_<%= resource_name %>.
 #
@@ -9,19 +14,27 @@
 class <%= class_name %>Tools < ActiveAgent::SchemaTools
   model <%= class_name %>
 
+<% if (declared = declared_columns(:filterable)) -%>
+  filterable <%= column_list(declared) %>
+<% else -%>
   filterable :id
 <% if suggested_columns.any? -%>
   # filterable <%= suggested_columns.map { |name, _type| ":#{name}" }.join(", ") %>
 <% else -%>
   # filterable :status, :owner_id   # columns an agent may filter on
 <% end -%>
+<% end -%>
 
+<% if (declared = declared_columns(:returns)) -%>
+  returns <%= column_list(declared) %>
+<% else -%>
   returns :id
 <% if suggested_columns.any? -%>
   # returns <%= suggested_columns.map { |name, _type| ":#{name}" }.join(", ") %>
 <% else -%>
   # returns :id, :title, :status    # columns an agent may read back
 <% end -%>
+<% end -%>
 <% if suggested_columns.any? -%>
   #
   # Columns and their types:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activeagent
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  version: 1.9.0
 platform: ruby
 authors:
 - Justin Bowen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -186,6 +186,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: openai
   requirement: !ruby/object:Gem::Requirement
@@ -419,6 +433,7 @@ files:
 - lib/active_agent/concerns/authorization.rb
 - lib/active_agent/concerns/callbacks.rb
 - lib/active_agent/concerns/delegation.rb
+- lib/active_agent/concerns/input_requests.rb
 - lib/active_agent/concerns/observers.rb
 - lib/active_agent/concerns/parameterized.rb
 - lib/active_agent/concerns/preview.rb
@@ -440,6 +455,7 @@ files:
 - lib/active_agent/delegation/schema.rb
 - lib/active_agent/deprecator.rb
 - lib/active_agent/evals.rb
+- lib/active_agent/evals/catalog.rb
 - lib/active_agent/evals/correlation.rb
 - lib/active_agent/evals/design_tokens.rb
 - lib/active_agent/evals/diagnosis.rb
@@ -451,6 +467,7 @@ files:
 - lib/active_agent/evals/report.rb
 - lib/active_agent/evals/report_html.rb
 - lib/active_agent/evals/result.rb
+- lib/active_agent/evals/ruby_llm.rb
 - lib/active_agent/evals/runner.rb
 - lib/active_agent/evals/scenario.rb
 - lib/active_agent/evals/scenario_parser.rb
@@ -459,6 +476,8 @@ files:
 - lib/active_agent/generation.rb
 - lib/active_agent/generation_job.rb
 - lib/active_agent/inline_preview_interceptor.rb
+- lib/active_agent/input_request.rb
+- lib/active_agent/input_request/resume.rb
 - lib/active_agent/model_capabilities.rb
 - lib/active_agent/providers/_base_provider.rb
 - lib/active_agent/providers/anthropic/_types.rb
@@ -492,14 +511,24 @@ files:
 - lib/active_agent/providers/common/responses/prompt.rb
 - lib/active_agent/providers/common/usage.rb
 - lib/active_agent/providers/concerns/exception_handler.rb
+- lib/active_agent/providers/concerns/input_requests.rb
 - lib/active_agent/providers/concerns/instrumentation.rb
+- lib/active_agent/providers/concerns/mcp_serving.rb
 - lib/active_agent/providers/concerns/previewable.rb
 - lib/active_agent/providers/concerns/tool_choice_clearing.rb
+- lib/active_agent/providers/deep_seek_provider.rb
+- lib/active_agent/providers/deepseek/_types.rb
+- lib/active_agent/providers/deepseek/chat/_types.rb
+- lib/active_agent/providers/deepseek/chat/request.rb
+- lib/active_agent/providers/deepseek/options.rb
+- lib/active_agent/providers/deepseek_provider.rb
 - lib/active_agent/providers/errors.rb
 - lib/active_agent/providers/gemini/_types.rb
 - lib/active_agent/providers/gemini/options.rb
 - lib/active_agent/providers/gemini_provider.rb
 - lib/active_agent/providers/log_subscriber.rb
+- lib/active_agent/providers/mcp_bridge.rb
+- lib/active_agent/providers/mcp_tool_cache.rb
 - lib/active_agent/providers/mock/_types.rb
 - lib/active_agent/providers/mock/embedding_request.rb
 - lib/active_agent/providers/mock/messages/_types.rb