ruby_llm-agents 3.9.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6925b14509a50c3bbf5efb8d0e37f5a38b4d2f52f13f3c7ecd7af588f832c5c1
-  data.tar.gz: 4332d03ebaf4bd94f3e314656e7f6755475c5ad45661a8c1e76e6e324d37ec2e
+  metadata.gz: 00477ed5ab4c97d2b28bb0b697288882744f1c377613224361233e0b3a145273
+  data.tar.gz: bac4d24f3599fbf7f3045e5ac41b1e85d047d74491b5dcc1dfb1c47cc85a5f60
 SHA512:
-  metadata.gz: e12ea68a14b7c9ec683ae7b07a14d9d422922fc8e5233d7296fd42bc6100097bb929da87b6c52fe55929779a17c04e59253fa490c40147558392a32a79023fa6
-  data.tar.gz: 9d0d5d249ee0bb6bac741d5c1087ade27ba0a6d032184bb01e1ecfc0d43f79453fbd12cd22e9e4f3eeca7b457bfb242ebca7ebc4e010f44387b9ee8a13bf0865
+  metadata.gz: 29ac67e031dc46d3b0d19f91843e6b2e034f0246445a5ad1d6ce453a2782f41948a92947a3a6e36d177d381756858185f87aa9b07d723123e1af3914f66ab136
+  data.tar.gz: d479f5076373eea1f30d8c797cd885d0788c7a081860a72fd69ee5dc3f77631860577eab91c14c09dd7f9fda709da41de90fb74b8a626b9094145f071e19259b

data/app/models/ruby_llm/agents/execution.rb

@@ -74,6 +74,10 @@ module RubyLLM
       has_one :detail, class_name: "RubyLLM::Agents::ExecutionDetail",
         foreign_key: :execution_id, dependent: :destroy
 
+      # Individual tool call records (real-time tracking)
+      has_many :tool_executions, class_name: "RubyLLM::Agents::ToolExecution",
+        foreign_key: :execution_id, dependent: :destroy
+
       # Delegations so existing code keeps working transparently
       delegate :system_prompt, :user_prompt, :assistant_prompt, :response, :error_message,
         :messages_summary, :tool_calls, :attempts, :fallback_chain,

data/app/models/ruby_llm/agents/tool_execution.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Tracks individual tool calls within an agent execution.
+    #
+    # Created in real-time as each tool runs (INSERT on start, UPDATE on complete),
+    # enabling live dashboard views and queryable tool-level analytics.
+    #
+    # @example Querying tool executions
+    #   execution.tool_executions.where(status: "error")
+    #   ToolExecution.where(tool_name: "bash").where("duration_ms > ?", 10_000)
+    #
+    class ToolExecution < ::ActiveRecord::Base
+      self.table_name = "ruby_llm_agents_tool_executions"
+
+      VALID_STATUSES = %w[running success error timed_out cancelled].freeze
+
+      belongs_to :execution, class_name: "RubyLLM::Agents::Execution"
+
+      validates :tool_name, presence: true
+      validates :status, presence: true, inclusion: {in: VALID_STATUSES}
+    end
+  end
+end

data/lib/ruby_llm/agents/base_agent.rb

@@ -730,6 +730,8 @@ module RubyLLM
         capture_response(response, context)
         result = build_result(process_response(response), response, context)
         context.output = result
+      rescue RubyLLM::Agents::CancelledError
+        context.output = Result.new(content: nil, cancelled: true)
       rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
         raise_with_setup_hint(e, context)
       rescue RubyLLM::ModelNotFoundError => e

data/lib/ruby_llm/agents/core/configuration.rb

@@ -387,6 +387,7 @@ module RubyLLM
         :default_total_timeout,
         :default_streaming,
         :default_tools,
+        :default_tool_timeout,
         :default_thinking,
         :on_alert,
         :persist_prompts,
@@ -639,6 +640,7 @@ module RubyLLM
         # Streaming, tools, and thinking defaults
         @default_streaming = false
         @default_tools = []
+        @default_tool_timeout = nil
         @default_thinking = nil
 
         # Governance defaults

data/lib/ruby_llm/agents/core/errors.rb

@@ -29,6 +29,9 @@ module RubyLLM
     # Raised when an execution cannot be replayed
     class ReplayError < Error; end
 
+    # Raised when an agent execution is cancelled via on_cancelled
+    class CancelledError < Error; end
+
     # Raised when the TTS API returns an error response
     class SpeechApiError < Error
       attr_reader :status, :response_body

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.9.0"
+    VERSION = "3.10.0"
   end
 end

data/lib/ruby_llm/agents/pipeline/middleware/budget.rb

@@ -124,7 +124,7 @@ module RubyLLM
                 tenant.record_execution!(
                   cost: context.total_cost || 0,
                   tokens: context.total_tokens || 0,
-                  error: context.error?
+                  error: context.failed?
                 )
                 return
               end
@@ -146,8 +146,6 @@ module RubyLLM
                 tenant_id: context.tenant_id
               )
             end
-          rescue => e
-            error("Failed to record spend: #{e.message}", context)
           end
         end
       end

data/lib/ruby_llm/agents/results/base.rb

@@ -112,6 +112,11 @@ module RubyLLM
       #   @return [String, nil] The agent class that produced this result
       attr_reader :agent_class_name
 
+      # @!group Cancellation
+      # @!attribute [r] cancelled
+      #   @return [Boolean] Whether the execution was cancelled
+      attr_reader :cancelled
+
       # @!group Debug
       # @!attribute [r] trace
       #   @return [Array<Hash>, nil] Pipeline trace entries (when debug: true)
@@ -173,6 +178,9 @@ module RubyLLM
         # Tracking
         @agent_class_name = options[:agent_class_name]
 
+        # Cancellation
+        @cancelled = options[:cancelled] || false
+
         # Debug trace
         @trace = options[:trace]
 
@@ -222,6 +230,13 @@ module RubyLLM
         !success?
       end
 
+      # Returns whether the execution was cancelled
+      #
+      # @return [Boolean] true if cancelled
+      def cancelled?
+        cancelled == true
+      end
+
       # Returns whether a fallback model was used
       #
       # @return [Boolean] true if chosen_model_id differs from model_id

data/lib/ruby_llm/agents/tool.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module RubyLLM
+  module Agents
+    # Base class for tools that need access to the agent's execution context.
+    #
+    # Inherits from RubyLLM::Tool and adds:
+    # - `context` accessor: read agent params, tenant, execution ID
+    # - `timeout` DSL: per-tool timeout in seconds
+    # - Error handling: exceptions become error strings for the LLM
+    # - Tool execution tracking: records each tool call in the database
+    #
+    # Users implement `execute()` — the standard RubyLLM convention.
+    # This class overrides `call()` to wrap execution with its features.
+    #
+    # @example Defining a tool
+    #   class BashTool < RubyLLM::Agents::Tool
+    #     description "Run a shell command"
+    #     timeout 30
+    #
+    #     param :command, desc: "The command to run", required: true
+    #
+    #     def execute(command:)
+    #       context.container_id  # reads agent param
+    #       # ... run command ...
+    #     end
+    #   end
+    #
+    # @example Using with an agent
+    #   class CodingAgent < ApplicationAgent
+    #     param :container_id, required: true
+    #     tools [BashTool]
+    #   end
+    #
+    #   CodingAgent.call(query: "list files", container_id: "abc123")
+    #
+    class Tool < RubyLLM::Tool
+      # The execution context, set before each call.
+      # Provides access to agent params, tenant, execution ID.
+      #
+      # @return [ToolContext, nil]
+      attr_reader :context
+
+      class << self
+        # Sets or gets the per-tool timeout in seconds.
+        #
+        # @param value [Integer, nil] Timeout in seconds (setter)
+        # @return [Integer, nil] The configured timeout (getter)
+        def timeout(value = nil)
+          if value
+            @timeout = value
+          else
+            @timeout
+          end
+        end
+      end
+
+      # Wraps RubyLLM's call() with context, timeout, tracking, and error handling.
+      #
+      # RubyLLM's Chat calls tool.call(args) during the tool loop.
+      # We set up context, create a tracking record, apply timeout,
+      # then delegate to super (which validates args and calls execute).
+      #
+      # @param args [Hash] Tool arguments from the LLM
+      # @return [String, Tool::Halt] The tool result or a Halt signal
+      def call(args)
+        pipeline_context = Thread.current[:ruby_llm_agents_caller_context]
+        @context = pipeline_context ? ToolContext.new(pipeline_context) : nil
+
+        record = start_tool_tracking(pipeline_context, args)
+
+        check_cancelled!(pipeline_context)
+
+        timeout_seconds = self.class.timeout
+        timeout_seconds ||= RubyLLM::Agents.configuration.default_tool_timeout
+
+        result = if timeout_seconds
+          Timeout.timeout(timeout_seconds) { super }
+        else
+          super
+        end
+
+        complete_tool_tracking(record, result, status: "success")
+        result
+      rescue Timeout::Error
+        complete_tool_tracking(record, nil, status: "timed_out", error: "Timed out after #{timeout_seconds}s")
+        "TIMEOUT: Tool did not complete within #{timeout_seconds}s."
+      rescue RubyLLM::Agents::CancelledError
+        complete_tool_tracking(record, nil, status: "cancelled")
+        raise # Let cancellation propagate to BaseAgent
+      rescue => e
+        complete_tool_tracking(record, nil, status: "error", error: e.message)
+        "ERROR (#{e.class}): #{e.message}"
+      end
+
+      private
+
+      # Creates a "running" ToolExecution record before the tool runs.
+      # Silently skips if no execution_id or ToolExecution is not available.
+      #
+      # @param pipeline_context [Pipeline::Context, nil]
+      # @param args [Hash] The tool arguments
+      # @return [ToolExecution, nil]
+      def start_tool_tracking(pipeline_context, args)
+        return nil unless pipeline_context&.execution_id
+        return nil unless defined?(ToolExecution)
+
+        @tool_iteration = (@tool_iteration || 0) + 1
+
+        ToolExecution.create!(
+          execution_id: pipeline_context.execution_id,
+          tool_name: name,
+          iteration: @tool_iteration,
+          status: "running",
+          input: normalize_input(args),
+          started_at: Time.current
+        )
+      rescue => e
+        # Don't let tracking failures break tool execution
+        Rails.logger.debug("[RubyLLM::Agents::Tool] Tracking failed: #{e.message}") if defined?(Rails) && Rails.logger
+        nil
+      end
+
+      # Updates the ToolExecution record after the tool completes.
+      #
+      # @param record [ToolExecution, nil]
+      # @param result [Object, nil] The tool result
+      # @param status [String] Final status
+      # @param error [String, nil] Error message
+      def complete_tool_tracking(record, result, status:, error: nil)
+        return unless record
+
+        completed_at = Time.current
+        duration_ms = record.started_at ? ((completed_at - record.started_at) * 1000).to_i : nil
+        output_str = result.is_a?(RubyLLM::Tool::Halt) ? result.content.to_s : result.to_s
+
+        record.update!(
+          status: status,
+          output: truncate_output(output_str),
+          output_bytes: output_str.bytesize,
+          error_message: error,
+          completed_at: completed_at,
+          duration_ms: duration_ms
+        )
+      rescue => e
+        Rails.logger.debug("[RubyLLM::Agents::Tool] Tracking update failed: #{e.message}") if defined?(Rails) && Rails.logger
+      end
+
+      def check_cancelled!(pipeline_context)
+        return unless pipeline_context
+        on_cancelled = pipeline_context[:on_cancelled]
+        return unless on_cancelled.respond_to?(:call)
+        raise CancelledError, "Execution cancelled" if on_cancelled.call
+      end
+
+      def normalize_input(args)
+        return {} if args.nil?
+        args.respond_to?(:to_h) ? args.to_h : {}
+      end
+
+      def truncate_output(str)
+        max = RubyLLM::Agents.configuration.try(:tool_result_max_length) || 10_000
+        (str.length > max) ? str[0, max] + "... (truncated)" : str
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/tool_context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Read-only wrapper around Pipeline::Context for tool authors.
+    #
+    # Exposes agent params and execution metadata to tools without
+    # leaking pipeline internals. Supports both method-style and
+    # hash-style access to agent params.
+    #
+    # @example Method-style access
+    #   context.container_id   # reads agent param
+    #   context.tenant_id      # fixed attribute
+    #
+    # @example Hash-style access
+    #   context[:container_id]
+    #
+    class ToolContext
+      # Execution record ID — links tool calls to the agent execution
+      #
+      # @return [Integer, nil]
+      def id
+        @ctx.execution_id
+      end
+
+      # Tenant ID from the pipeline context
+      #
+      # @return [String, nil]
+      def tenant_id
+        @ctx.tenant_id
+      end
+
+      # Agent class name
+      #
+      # @return [String, nil]
+      def agent_type
+        @ctx.agent_class&.name
+      end
+
+      # Hash-style access to agent params
+      #
+      # @param key [Symbol, String] The param key
+      # @return [Object, nil]
+      def [](key)
+        @agent_options[key.to_sym] || @agent_options[key.to_s]
+      end
+
+      def initialize(pipeline_context)
+        @ctx = pipeline_context
+        @agent_options = @ctx.agent_instance&.send(:options) || {}
+      end
+
+      private
+
+      # Method-style access to agent params
+      def method_missing(method_name, *args)
+        key = method_name.to_sym
+        if @agent_options.key?(key) || @agent_options.key?(key.to_s)
+          self[key]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        key = method_name.to_sym
+        @agent_options.key?(key) || @agent_options.key?(key.to_s) || super
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents.rb

@@ -26,6 +26,10 @@ require_relative "agents/base_agent"
 # Agent-as-Tool adapter
 require_relative "agents/agent_tool"
 
+# Tool base class and context for coding agents
+require_relative "agents/tool_context"
+require_relative "agents/tool"
+
 # Infrastructure - Budget & Utilities
 require_relative "agents/infrastructure/circuit_breaker"
 require_relative "agents/infrastructure/budget_tracker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.10.0
 platform: ruby
 authors:
 - adham90
@@ -98,6 +98,7 @@ files:
 - app/models/ruby_llm/agents/tenant/resettable.rb
 - app/models/ruby_llm/agents/tenant/trackable.rb
 - app/models/ruby_llm/agents/tenant_budget.rb
+- app/models/ruby_llm/agents/tool_execution.rb
 - app/services/ruby_llm/agents/agent_registry.rb
 - app/views/layouts/ruby_llm/agents/application.html.erb
 - app/views/ruby_llm/agents/agents/_config_agent.html.erb
@@ -326,6 +327,8 @@ files:
 - lib/ruby_llm/agents/routing/class_methods.rb
 - lib/ruby_llm/agents/routing/result.rb
 - lib/ruby_llm/agents/text/embedder.rb
+- lib/ruby_llm/agents/tool.rb
+- lib/ruby_llm/agents/tool_context.rb
 - lib/ruby_llm/agents/track_report.rb
 - lib/ruby_llm/agents/tracker.rb
 - lib/tasks/ruby_llm_agents.rake