solid_agent 0.0.0 → 0.2.0

data/lib/solid_agent/records/agent_version.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  module Records
+    # Version history for an agent's configuration.
+    #
+    # Every time an agent's versioned attributes change, the host writes a new
+    # row holding a full snapshot of the configuration at that moment. Snapshots
+    # are whole, not deltas: a version has to be restorable on its own, long
+    # after the rows around it were pruned, and diffing is cheap enough to do in
+    # Ruby.
+    #
+    # The +agent+ association is named with the configured class *string*
+    # (SolidAgent.agent_class) rather than a constant, so the host can point the
+    # records layer at +Ai::Assistant+ without the gem ever touching an
+    # autoloadable constant during load.
+    #
+    # Nothing here uses jsonb operators, so the concern works the same on
+    # Postgres, MySQL and sqlite; comparison happens in Ruby.
+    #
+    # @example Diffing two versions
+    #   v2.diff(v1)
+    #   #=> { "model" => { from: "gpt-4o-mini", to: "gpt-4o" },
+    #   #     "tools" => { from: nil, to: ["search"] } }
+    #
+    # @example Walking the history
+    #   version.previous      #=> the next-lower version, or nil at v1
+    #   version.next_version  #=> the next-higher version, or nil at the tip
+    module AgentVersion
+      extend ActiveSupport::Concern
+
+      included do
+        # class_name is read as a String at include time — the host configures
+        # SolidAgent in an initializer, which always runs before app/models is
+        # autoloaded, and Rails resolves the string to a class only on first
+        # use. Constantizing here instead would pin a class that a code reload
+        # then replaces.
+        # optional: false is spelled out rather than inherited from the host's
+        # belongs_to_required_by_default: agent_id is NOT NULL, so an app that
+        # loads older Rails defaults would otherwise trade a validation error
+        # for a NotNullViolation.
+        belongs_to :agent, class_name: SolidAgent.agent_class.to_s, optional: false
+
+        # Mirrors the unique index on [agent_id, version_number]. The index is
+        # the real guarantee; the validation exists to fail with a readable
+        # error instead of a RecordNotUnique from the adapter.
+        validates :version_number, presence: true, uniqueness: { scope: :agent_id }
+        validates :configuration_snapshot, presence: true
+
+        scope :recent, -> { order(version_number: :desc) }
+        scope :by_version, ->(number) { where(version_number: number) }
+      end
+
+      # Compares this version's snapshot against another's.
+      #
+      # The result is keyed by configuration key and reads from the *other*
+      # version to this one, so `newer.diff(older)` describes what the newer
+      # version changed.
+      #
+      # Both key sets are unioned, which means a key dropped in this version is
+      # reported as `{ from: <old value>, to: nil }` rather than silently
+      # skipped. Keys are compared as strings, because a snapshot built in
+      # memory carries symbol keys while one loaded from a json column carries
+      # strings, and the two must not read as a wholesale rewrite.
+      #
+      # @param other_version [#configuration_snapshot, nil]
+      # @return [Hash{String => Hash}] changed keys to +{ from:, to: }+
+      #
+      # @example A removed key
+      #   v1.update!(configuration_snapshot: { "model" => "gpt-4o", "tools" => ["search"] })
+      #   v2.update!(configuration_snapshot: { "model" => "gpt-4o" })
+      #   v2.diff(v1) #=> { "tools" => { from: ["search"], to: nil } }
+      def diff(other_version)
+        return {} unless other_version
+
+        mine = normalized_snapshot(configuration_snapshot)
+        theirs = normalized_snapshot(other_version.configuration_snapshot)
+
+        (mine.keys | theirs.keys).each_with_object({}) do |key, changes|
+          before = theirs[key]
+          after = mine[key]
+          changes[key] = { from: before, to: after } unless before == after
+        end
+      end
+
+      # The nearest version below this one, or nil when this is the first.
+      #
+      # @return [ActiveRecord::Base, nil]
+      def previous
+        sibling_versions.where("version_number < ?", version_number).order(version_number: :desc).first
+      end
+
+      # The nearest version above this one, or nil when this is the tip.
+      #
+      # @return [ActiveRecord::Base, nil]
+      def next_version
+        sibling_versions.where("version_number > ?", version_number).order(version_number: :asc).first
+      end
+
+      # Whether no higher-numbered version exists for the same agent.
+      #
+      # Answered from the version table alone rather than by asking the agent
+      # for its latest version: the gem owns no part of the host's Agent model
+      # and must not require it to expose a +latest_version+ reader.
+      #
+      # @return [Boolean]
+      def latest?
+        return false if version_number.nil?
+
+        !sibling_versions.where("version_number > ?", version_number).exists?
+      end
+
+      # Whether this is version 1.
+      #
+      # Deliberately a property of the numbering, not of the surviving rows —
+      # after old versions are pruned the oldest remaining row is not the
+      # initial configuration and should not claim to be.
+      #
+      # @return [Boolean]
+      def initial?
+        version_number == 1
+      end
+
+      private
+
+      # Versions of the same agent, queried through the concrete host class.
+      # Going through the class rather than +agent.agent_versions+ keeps the
+      # gem from assuming what the host named the inverse association, and
+      # avoids loading the agent row just to walk sibling versions.
+      def sibling_versions
+        self.class.where(agent_id: agent_id)
+      end
+
+      def normalized_snapshot(snapshot)
+        return {} if snapshot.blank?
+
+        snapshot.to_h.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/solid_agent/records/ownable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  module Records
+    # Configurable ownership for the agent records.
+    #
+    # Tenancy is the one thing every application has already decided before it
+    # installs this gem. The platform scopes agents to a plain +user_id+; a
+    # multi-tenant host scopes them to an account, a workspace, an organization.
+    # Hardcoding +belongs_to :user+ would force one of those to migrate, and
+    # hardcoding nothing would leave every consumer to reinvent the same scope.
+    #
+    # So the concern declares the association from two class attributes, and
+    # everything else in the gem talks to it through the +owner+ pair — which is
+    # why {AgentTemplate#create_agent_for} can assign an owner it knows nothing
+    # about.
+    #
+    # The +belongs_to+ is declared with a class *name*, never a class: host
+    # models are autoloaded, and constantizing +User+ while the gem's concern is
+    # being included either deadlocks the Rails loader or pins a class that the
+    # next code reload replaces. It is also +optional: true+, because a
+    # single-user install legitimately has agents that belong to nobody.
+    #
+    # @example The default: agents own a user_id column
+    #   class Agent < ApplicationRecord
+    #     include SolidAgent::Records::Ownable
+    #   end
+    #
+    #   agent.owner = current_user
+    #   Agent.for_owner(current_user)
+    #
+    # @example A multi-tenant host
+    #   class Agent < ApplicationRecord
+    #     include SolidAgent::Records::Ownable
+    #     owned_by :account, class_name: "Tenancy::Account"
+    #   end
+    #
+    #   Agent.owner_foreign_key #=> "account_id"
+    module Ownable
+      extend ActiveSupport::Concern
+
+      included do
+        # instance_writer is off deliberately: ownership mapping is a property
+        # of the model, and a record that could rewrite it would make
+        # `for_owner` and `owner` disagree for the length of a request.
+        class_attribute :owner_association, instance_writer: false, default: :user
+        class_attribute :owner_class_name, instance_writer: false, default: "User"
+
+        declare_owner_association
+
+        # Restricts to one owner — and to nothing at all when the host has no
+        # ownership column, where it returns every record instead of raising.
+        # A single-tenant install still calls `for_owner(current_user)` from
+        # shared code paths, and there the honest answer to "which of these are
+        # yours" is "all of them", not StatementInvalid.
+        scope :for_owner, ->(owner) {
+          klass.owner_column? ? where(klass.owner_foreign_key => owner) : all
+        }
+      end
+
+      class_methods do
+        # Points ownership at a different association.
+        #
+        # @param association [Symbol, String] association name, e.g. +:account+
+        # @param class_name [String, nil] owner model name; defaults to the
+        #   association name camelized
+        # @param options [Hash] passed through to +belongs_to+ (+foreign_key+,
+        #   +inverse_of+, +optional: false+ to require an owner, …)
+        # @return [void]
+        #
+        # @example Requiring an owner
+        #   owned_by :account, class_name: "Account", optional: false
+        def owned_by(association, class_name: nil, **options)
+          self.owner_association = association.to_sym
+          self.owner_class_name = (class_name.presence || association.to_s.camelize).to_s
+
+          declare_owner_association(**options)
+        end
+
+        # The column ownership is stored in.
+        #
+        # Read from the reflection rather than assembled from the association
+        # name, so a host that passed a custom +foreign_key+ to {owned_by} gets
+        # the column it actually chose.
+        #
+        # @return [String]
+        def owner_foreign_key
+          reflect_on_association(owner_association)&.foreign_key&.to_s || "#{owner_association}_id"
+        end
+
+        # Whether this model actually stores an owner.
+        #
+        # Consults the schema rather than the declaration: the association is
+        # always declared, and a host that generated the tables without an
+        # ownership column is a supported install, not a broken one.
+        #
+        # @return [Boolean]
+        def owner_column?
+          column_names.include?(owner_foreign_key)
+        end
+
+        private
+
+        def declare_owner_association(**options)
+          belongs_to owner_association, **{ class_name: owner_class_name, optional: true }.merge(options)
+        end
+      end
+
+      # The record this one belongs to, or nil when the host stores no owner.
+      #
+      # Defined as a method rather than +alias_method+ because the underlying
+      # association is per-class configuration: an alias would bind to whatever
+      # {owned_by} had been called with at include time, and a subclass that
+      # re-owned itself would silently keep reading the parent's association.
+      #
+      # @return [Object, nil]
+      def owner
+        return nil unless self.class.owner_column?
+
+        public_send(self.class.owner_association)
+      end
+
+      # @param record [Object, nil] the owning record
+      # @return [Object, nil] the assigned record
+      def owner=(record)
+        public_send(:"#{self.class.owner_association}=", record)
+      end
+    end
+  end
+end

data/lib/solid_agent/records.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  # Behavior for the agent-configuration records: the agent itself, its version
+  # history, the templates it can be created from, and its runs.
+  #
+  # The gem ships behavior only. The model classes are host-owned — generated
+  # into +app/models+ by `rails generate solid_agent:agents` — and the gem
+  # never defines or requires the +Agent+, +AgentVersion+, +AgentTemplate+ or
+  # +AgentRun+ constants. That is deliberate, for three reasons:
+  #
+  # * ActiveAgent's dashboard cannot depend on solid_agent — solid_agent
+  #   already depends on activeagent, so the reverse edge would be a cycle.
+  #   Naming the models with configurable strings and resolving them at call
+  #   time is what lets both the dashboard and a plain host app read the same
+  #   tables without either gem requiring the other.
+  # * Engine-namespacing them as +SolidAgent::Agent+ would make
+  #   +isolate_namespace+ resolve the table to +solid_agent_agents+, and would
+  #   invalidate the +contextable_type: "Agent"+ strings already persisted in
+  #   production +agent_contexts+ rows.
+  # * Agent configuration is the thing applications most want to extend. A
+  #   host-owned model can be edited; a gem-owned one can only be monkey-patched.
+  #
+  # @example Resolving the configured model
+  #   SolidAgent.agent_model            #=> Agent
+  #   SolidAgent.agent_model_name       #=> "Agent"
+  #   SolidAgent.records_installed?     #=> true
+  #
+  # @example Pointing at differently-named models
+  #   SolidAgent.configure do |config|
+  #     config.agent_class = "Ai::Assistant"
+  #     config.agent_run_class = "Ai::AssistantRun"
+  #   end
+  module Records
+    # Model names the gem resolves lazily, and their defaults.
+    MODELS = {
+      agent_class: "Agent",
+      agent_version_class: "AgentVersion",
+      agent_template_class: "AgentTemplate",
+      agent_run_class: "AgentRun"
+    }.freeze
+  end
+
+  class << self
+    Records::MODELS.each_key { |name| attr_writer name }
+
+    Records::MODELS.each do |name, default|
+      # Configured class name, as a String. Never constantized at load time —
+      # host models are autoloaded, and touching them during gem load either
+      # deadlocks the Rails loader or pins a stale class across a reload.
+      define_method(name) { instance_variable_get(:"@#{name}") || default }
+
+      # The resolved class, or nil when the host has not generated it.
+      #
+      # @return [Class, nil]
+      reader = name.to_s.sub(/_class\z/, "_model")
+      define_method(reader) { public_send(name).to_s.safe_constantize }
+
+      # The resolved class, raising a directive error when absent.
+      #
+      # @raise [SolidAgent::Error]
+      define_method("#{reader}!") do
+        public_send(reader) ||
+          raise(Error, "#{public_send(name)} is not defined. Run `rails generate solid_agent:agents` " \
+                       "to create it, or set SolidAgent.#{name} to the model you use instead.")
+      end
+    end
+
+    # Whether the agent-records models are present and backed by tables.
+    #
+    # Consumers that must degrade gracefully — ActiveAgent's dashboard being
+    # the motivating one — check this before touching the models. It answers
+    # false both when the constant is missing and when the migration has not
+    # run, because a defined model over a missing table fails later and less
+    # legibly.
+    #
+    # @return [Boolean]
+    def records_installed?
+      model = agent_model
+      return false unless model
+
+      model.respond_to?(:table_exists?) && model.table_exists?
+    rescue ::StandardError
+      # A connection that is not established yet is not an error worth raising
+      # from a predicate whose whole job is to be safe to call.
+      false
+    end
+
+    # Executes an agent record and returns its result.
+    #
+    # Running an agent from a persisted configuration means building a class
+    # from stored provider/model/instructions and driving it — execution
+    # concerns, which belong to activeagent and to the host, not to a
+    # persistence gem. So the gem defines the seam and the host fills it.
+    #
+    # The callable receives +(agent_record, run)+ and must return a Hash with
+    # +:output+ and optionally +:metadata+ and +:usage+.
+    #
+    # @example
+    #   SolidAgent.run_executor = ->(agent_record, run) { AgentExecutionService.call(agent_record, run) }
+    #
+    # @return [#call]
+    def run_executor
+      @run_executor ||= lambda do |agent_record, _run|
+        raise Error, "No SolidAgent.run_executor is configured, so #{agent_record.class} cannot be executed. " \
+                     "Set SolidAgent.run_executor to a callable taking (agent_record, run) and returning " \
+                     "{ output:, metadata:, usage: }."
+      end
+    end
+
+    attr_writer :run_executor
+
+    # Job class enqueued by asynchronous execution, resolved at call time.
+    #
+    # @return [String]
+    def execution_job_class
+      @execution_job_class || "AgentExecutionJob"
+    end
+
+    attr_writer :execution_job_class
+
+    # @return [Class, nil]
+    def execution_job = execution_job_class.to_s.safe_constantize
+
+    # Resets every records-layer configuration knob. Test support.
+    #
+    # @return [void]
+    def reset_records_configuration!
+      Records::MODELS.each_key { |name| instance_variable_set(:"@#{name}", nil) }
+      @run_executor = nil
+      @execution_job_class = nil
+    end
+  end
+end
+
+# The concerns load after the seam above, so a `belongs_to` reading
+# SolidAgent.agent_class from an `included do` block can never outrun the
+# reader that answers it.
+#
+# They are required eagerly, and that is safe precisely because none of them
+# touches an ActiveRecord API at load time: every `belongs_to`, `enum`,
+# `validates` and `scope` lives inside an `included do` or `class_methods`
+# block, which Ruby stores as a block and runs only when a host model includes
+# the concern. So `require "solid_agent"` in a process with no ActiveRecord —
+# a rake task, a manifest-only consumer — defines these modules and loads
+# nothing else. If a concern ever needs an AR constant at load time, it belongs
+# behind an `ActiveSupport.on_load(:active_record)` hook, not in this list.
+require_relative "records/ownable"
+require_relative "records/agent"
+require_relative "records/agent_version"
+require_relative "records/agent_template"
+require_relative "records/agent_run"

data/lib/solid_agent/run_fingerprint.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SolidAgent
+  # Stable fingerprints for the instructions a run executed under — the
+  # grouping key (with model) for configuration cohorts when comparing
+  # instruction/model changes across runs.
+  #
+  # @example Digest and codename
+  #   digest = SolidAgent::RunFingerprint.digest("You are a helpful agent.")
+  #   # => "a1b2c3d4"
+  #   SolidAgent::RunFingerprint.codename(digest)
+  #   # => "calm-heron"
+  module RunFingerprint
+    # Deterministic memorable names for digests — they read far better
+    # than hex when comparing cohorts, and are stable across runs and
+    # deployments because they derive from the digest alone.
+    ADJECTIVES = %w[
+      calm brisk quiet bold amber coral dusky fresh golden keen
+      lively mellow nimble pale rustic silver tidal vivid wry zesty
+      arid breezy crisp dapper eager foggy hazy icy jolly lunar
+      misty polar
+    ].freeze
+    NOUNS = %w[
+      heron otter falcon cedar willow harbor mesa ridge grove delta
+      prairie summit canyon reef atoll fjord tundra oasis lagoon dune
+      glacier meadow bluff cove marsh basin knoll strait quarry vale
+      hollow crag
+    ].freeze
+
+    class << self
+      # @param instructions [String, nil]
+      # @return [String, nil] 8-hex-char digest, nil for blank input
+      def digest(instructions)
+        return nil if instructions.nil? || instructions.to_s.strip.empty?
+
+        Digest::SHA256.hexdigest(instructions.to_s)[0, 8]
+      end
+
+      # @param digest [String, nil] an 8-hex-char instructions digest
+      # @return [String, nil] deterministic "adjective-noun" codename
+      def codename(digest)
+        return nil if digest.nil? || digest.to_s.empty?
+
+        value = digest.to_s.to_i(16)
+        "#{ADJECTIVES[value % 32]}-#{NOUNS[(value / 32) % 32]}"
+      end
+    end
+  end
+end

data/lib/solid_agent/streams_tool_updates.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# StreamsToolUpdates provides real-time UI feedback during tool execution.
+#
+# When an agent is processing and calls tools (which may take time), this concern
+# broadcasts status updates to the client so users see what's happening rather than
+# a frozen UI. This is especially important for long-running tools like web browsing.
+#
+# @example Basic usage
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     include SolidAgent::StreamsToolUpdates
+#
+#     has_tools :search, :navigate
+#
+#     def research
+#       prompt(tools: tools)
+#     end
+#   end
+#
+# @example With custom descriptions
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     include SolidAgent::StreamsToolUpdates
+#
+#     tool_description :navigate, ->(args) { "Visiting #{args[:url]}..." }
+#     tool_description :search, ->(args) { "Searching for '#{args[:query]}'..." }
+#     tool_description :extract_text, "Reading page content..."
+#   end
+module SolidAgent
+  module StreamsToolUpdates
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_tool_descriptions, default: {}
+      class_attribute :_wrapped_tools, default: Set.new
+    end
+
+    class_methods do
+      # Defines a human-readable description for a tool that will be shown in the UI.
+      #
+      # @param tool_name [Symbol, String] the tool method name
+      # @param description [String, Proc] static string or proc that receives args
+      #
+      # @example Static description
+      #   tool_description :extract_text, "Reading page content..."
+      #
+      # @example Dynamic description with args
+      #   tool_description :navigate, ->(args) { "Visiting #{args[:url]}..." }
+      def tool_description(tool_name, description)
+        self._tool_descriptions = _tool_descriptions.merge(tool_name.to_sym => description)
+        wrap_tool_method(tool_name)
+      end
+
+      # Wraps a tool method to broadcast status before execution
+      #
+      # @param tool_name [Symbol, String] the tool method name
+      def wrap_tool_method(tool_name)
+        tool_sym = tool_name.to_sym
+        return if _wrapped_tools.include?(tool_sym)
+
+        self._wrapped_tools = _wrapped_tools.dup.add(tool_sym)
+
+        # Use prepend to wrap the method
+        wrapper_module = Module.new do
+          define_method(tool_sym) do |**kwargs|
+            broadcast_tool_status(tool_sym, kwargs) if should_broadcast_tools?
+            super(**kwargs)
+          end
+        end
+
+        prepend wrapper_module
+      end
+    end
+
+    private
+
+    def should_broadcast_tools?
+      params[:stream_id].present?
+    end
+
+    # Broadcasts a tool status update to the client
+    #
+    # @param tool_name [String, Symbol] the tool being executed
+    # @param args [Hash] the arguments passed to the tool
+    def broadcast_tool_status(tool_name, args = {})
+      return unless params[:stream_id]
+
+      description = tool_description_for(tool_name, args)
+
+      Rails.logger.info "[#{self.class.name}] Tool status: #{description}"
+
+      ActionCable.server.broadcast(
+        params[:stream_id],
+        {
+          tool_status: {
+            name: tool_name.to_s,
+            description: description,
+            timestamp: Time.current.iso8601
+          }
+        }
+      )
+    end
+
+    # Gets the human-readable description for a tool
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @param args [Hash] the arguments passed to the tool
+    # @return [String] description to show in UI
+    def tool_description_for(tool_name, args = {})
+      custom = _tool_descriptions[tool_name.to_sym]
+
+      if custom.is_a?(Proc)
+        custom.call(args)
+      elsif custom.is_a?(String)
+        custom
+      else
+        default_tool_description(tool_name, args)
+      end
+    end
+
+    # Generates a default description for common tool types
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @param args [Hash] the arguments passed to the tool
+    # @return [String] default description
+    def default_tool_description(tool_name, args = {})
+      case tool_name.to_s
+      when "navigate"
+        args[:url] ? "Visiting #{truncate_url(args[:url])}..." : "Navigating to page..."
+      when "click"
+        args[:text] ? "Clicking '#{args[:text]}'..." : "Clicking element..."
+      when "fill_form"
+        args[:field] ? "Filling in #{args[:field]}..." : "Filling form..."
+      when "extract_text", "extract_main_content"
+        "Reading page content..."
+      when "extract_links"
+        "Extracting links..."
+      when "page_info"
+        "Getting page info..."
+      when "go_back"
+        "Going back..."
+      when "search", "web_search"
+        args[:query] ? "Searching for '#{args[:query]}'..." : "Searching..."
+      when "read", "read_file"
+        args[:path] ? "Reading #{File.basename(args[:path])}..." : "Reading file..."
+      when "write", "write_file"
+        args[:path] ? "Writing #{File.basename(args[:path])}..." : "Writing file..."
+      else
+        "Performing #{tool_name.to_s.tr('_', ' ')}..."
+      end
+    end
+
+    # Truncates a URL for display
+    #
+    # @param url [String] the URL to truncate
+    # @param max_length [Integer] maximum length
+    # @return [String] truncated URL
+    def truncate_url(url, max_length: 50)
+      return url if url.length <= max_length
+
+      uri = URI.parse(url)
+      host = uri.host || url[0..max_length]
+      path = uri.path || ""
+
+      if host.length > max_length
+        "#{host[0..max_length]}..."
+      elsif (host.length + path.length) > max_length
+        remaining = max_length - host.length - 3
+        "#{host}#{path[0..remaining]}..."
+      else
+        "#{host}#{path}"
+      end
+    rescue URI::InvalidURIError
+      url.length > max_length ? "#{url[0..max_length]}..." : url
+    end
+  end
+end