solid_agent 0.1.1 → 0.2.1

data/lib/solid_agent/has_context.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
+require "digest"
+require "set"
+
 # HasContext provides database-backed prompt context management for agents.
 #
 # This concern adds the `has_context` class method which configures an agent
 # to persist its prompt context, messages, and generation results to the database.
 # It works similarly to ActiveRecord associations, allowing custom naming.
 #
-# @example Basic usage with auto-context (contextable inferred from params)
+# @example Basic usage with auto-context (contextual inferred from params)
 #   class WritingAssistantAgent < ApplicationAgent
 #     include SolidAgent::HasContext
-#     has_context contextable: :document  # Auto-creates context from params[:document]
+#     has_context contextual: :document  # Auto-creates context from params[:document]
 #
 #     def improve
 #       prompt  # Context automatically created before prompt
@@ -19,7 +22,7 @@
 # @example Named context with auto-creation
 #   class ChatAgent < ApplicationAgent
 #     include SolidAgent::HasContext
-#     has_context :conversation, contextable: :user  # Auto-loads/creates from params[:user]
+#     has_context :conversation, contextual: :user  # Auto-loads/creates from params[:user]
 #
 #     def chat
 #       add_conversation_user_message(params[:message])
@@ -27,10 +30,10 @@
 #     end
 #   end
 #
-# @example Manual context management (contextable: false)
+# @example Manual context management (contextual: false)
 #   class ResearchAgent < ApplicationAgent
 #     include SolidAgent::HasContext
-#     has_context :research_session, contextable: false
+#     has_context :research_session, contextual: false
 #
 #     def research
 #       create_research_session(contextable: params[:project])  # Manual creation
@@ -38,11 +41,11 @@
 #     end
 #   end
 #
-# @example Multiple contexts with different contextables
+# @example Multiple contexts with different contextual params
 #   class MultiModalAgent < ApplicationAgent
 #     include SolidAgent::HasContext
-#     has_context :conversation, contextable: :user      # Auto from params[:user]
-#     has_context :analysis, contextable: :document      # Auto from params[:document]
+#     has_context :conversation, contextual: :user      # Auto from params[:user]
+#     has_context :analysis, contextual: :document      # Auto from params[:document]
 #
 #     def analyze
 #       prompt  # Both contexts auto-created
@@ -79,26 +82,26 @@ module SolidAgent
       #
       # @param auto_save [Boolean] Automatically save generation results (default: true)
       #
-      # @param contextable [Symbol, false, nil] Param key for auto-context creation
-      #   - Symbol: Auto-load/create context using params[contextable] (e.g., :user, :document)
+      # @param contextual [Symbol, false, nil] Param key for auto-context creation
+      #   - Symbol: Auto-load/create context using params[contextual] (e.g., :user, :document)
       #   - false: Disable auto-context, require manual create_* or load_* calls
       #   - nil: Auto-create context without a contextable (anonymous context)
       #
       # @example Auto-context from params
-      #   has_context :conversation, contextable: :user
+      #   has_context :conversation, contextual: :user
       #
       # @example Manual context management
-      #   has_context :session, contextable: false
+      #   has_context :session, contextual: false
       #
       # @example Fully customized
       #   has_context :session,
       #               class_name: "ChatSession",
       #               message_class: "ChatMessage",
       #               generation_class: "ChatGeneration",
-      #               contextable: :chat_user,
+      #               contextual: :chat_user,
       #               auto_save: false
       #
-      def has_context(name = nil, class_name: nil, message_class: nil, generation_class: nil, auto_save: true, contextable: nil)
+      def has_context(name = nil, class_name: nil, message_class: nil, generation_class: nil, auto_save: true, contextual: nil)
         # Normalize name
         context_name = normalize_context_name(name)
 
@@ -111,7 +114,7 @@ module SolidAgent
           message_class: message_class || inferred_classes[:message],
           generation_class: generation_class || inferred_classes[:generation],
           auto_save: auto_save,
-          contextable: contextable
+          contextual: contextual
         }
 
         # Store configuration
@@ -129,10 +132,10 @@ module SolidAgent
           around_generation :capture_and_persist_generation
         end
 
-        # Add auto-context callback if contextable is not explicitly false
-        if contextable != false
+        # Add auto-context callback if contextual is not explicitly false
+        if contextual != false
           after_prompt :"ensure_#{context_name}_exists"
-          define_auto_context_method(context_name, contextable)
+          define_auto_context_method(context_name, contextual)
         end
       end
 
@@ -149,14 +152,19 @@ module SolidAgent
 
       def infer_class_names(context_name, explicit_class_name)
         if context_name == :context
+          # The default trio is configurable — SolidAgent.context_class and
+          # friends are what the shipped initializer tells hosts to set, so
+          # they have to be read here rather than hardcoded.
           {
-            context: "AgentContext",
-            message: "AgentMessage",
-            generation: "AgentGeneration"
+            context: SolidAgent.context_class,
+            message: SolidAgent.message_class,
+            generation: SolidAgent.generation_class
           }
         elsif explicit_class_name
-          # If class_name is provided, infer message/generation from it
-          base = explicit_class_name.to_s.delete_suffix("Context").delete_suffix("Session")
+          # If class_name is provided, infer message/generation from it.
+          # Strip at most one suffix: chaining delete_suffix would reduce
+          # "SessionContext" to "" and yield a bare "Message"/"Generation".
+          base = SolidAgent::ModelNaming.base_for(explicit_class_name)
           {
             context: explicit_class_name,
             message: "#{base}Message",
@@ -177,17 +185,17 @@ module SolidAgent
         attr_accessor context_name
       end
 
-      def define_auto_context_method(context_name, contextable_key)
+      def define_auto_context_method(context_name, contextual_key)
         # Define ensure_{name}_exists method that auto-creates context if not present
         define_method("ensure_#{context_name}_exists") do
           return if send(context_name).present?
 
           config = self.class._context_configs[context_name]
-          contextable_param = config[:contextable]
+          contextual_param = config[:contextual]
 
-          if contextable_param.is_a?(Symbol)
+          if contextual_param.is_a?(Symbol)
             # Load or create with contextable from params
-            contextable_value = params[contextable_param]
+            contextable_value = params[contextual_param]
             send("load_#{context_name}", contextable: contextable_value)
           else
             # Create anonymous context (no contextable)
@@ -282,7 +290,23 @@ module SolidAgent
         define_method("add_#{context_name}_message") do |role:, content:, **attributes|
           ctx = send(context_name)
           raise SolidAgent::Error, "No #{context_name} loaded. Call load_#{context_name} or create_#{context_name} first." unless ctx
-          ctx.messages.create!(role: role, content: content, **attributes)
+
+          # Build message attributes
+          message_attrs = { role: role, content: content, **attributes }
+
+          # Add provenance data if the message model supports it
+          # Check via the context's message association if available
+          begin
+            if ctx.messages.respond_to?(:build)
+              sample = ctx.messages.build
+              message_attrs[:provenance] = current_provenance if sample.respond_to?(:provenance=)
+              message_attrs[:content_checksum] = Digest::MD5.hexdigest(content.to_s) if sample.respond_to?(:content_checksum=)
+            end
+          rescue StandardError
+            # Ignore if we can't check - just create without extra fields
+          end
+
+          ctx.messages.create!(**message_attrs)
         end
 
         # Define add_{name}_user_message method
@@ -409,11 +433,144 @@ module SolidAgent
       send("#{primary_context_name}_summary")
     end
 
+    # ============================================
+    # Provenance & Checksums
+    # ============================================
+
+    # Generate checksum for current prompt configuration
+    #
+    # @return [String] MD5 hex digest
+    def prompt_checksum
+      data = {
+        instructions: prompt_options[:instructions],
+        model: prompt_options[:model],
+        temperature: prompt_options[:temperature],
+        tools: prompt_tool_roster.map { |tool| tool[:name] }.presence
+      }.compact
+      Digest::MD5.hexdigest(data.to_json)
+    end
+
+    # The tool schemas this generation actually offered the provider, as a
+    # compact roster.
+    #
+    # The full schemas are too heavy to persist on every generation, and
+    # the checksum above only proves the roster *changed* — it can't say
+    # what the agent could do. Recording names, descriptions and parameter
+    # keys makes the tool surface auditable straight from the generation
+    # records, without requiring telemetry to be switched on.
+    #
+    # Shape matches ActiveAgent's `prompt.input.tools` span attribute so a
+    # dashboard parses one format from both sources.
+    #
+    # @return [Array<Hash>] entries with :name, :description, :parameters
+    def prompt_tool_roster
+      Array(prompt_options[:tools]).filter_map do |tool|
+        next unless tool.respond_to?(:[])
+
+        name = tool[:name] || tool["name"]
+        next if name.blank?
+
+        parameters = tool[:parameters] || tool["parameters"] || tool[:input_schema] || tool["input_schema"]
+        properties = parameters.is_a?(Hash) ? (parameters[:properties] || parameters["properties"]) : nil
+
+        {
+          name: name.to_s,
+          description: (tool[:description] || tool["description"]).to_s.presence,
+          parameters: properties.is_a?(Hash) ? properties.keys.map(&:to_s) : []
+        }.compact
+      end
+    end
+
+    # Generate checksum for current context state
+    #
+    # @return [String, nil] MD5 hex digest or nil if no context
+    def context_checksum
+      return nil unless context
+      Digest::MD5.hexdigest({
+        context_id: context.id,
+        message_count: context.messages.size,
+        last_message_id: context.messages.last&.id
+      }.to_json)
+    end
+
+    # Generate provenance record for current agent state
+    #
+    # @return [Hash] Full provenance data for tracing
+    def current_provenance
+      {
+        agent_class: self.class.name,
+        agent_checksum: agent_checksum,
+        prompt_checksum: prompt_checksum,
+        context_checksum: context_checksum,
+        context_id: context&.id,
+        action_name: action_name,
+        trace_id: prompt_options[:trace_id],
+        timestamp: Time.now.iso8601,
+        manifest_fingerprint: manifest_fingerprint,
+        tools: prompt_tool_roster.presence
+      }.compact
+    end
+
+    # Generate checksum for the agent class configuration
+    #
+    # Class-level options are read defensively so provenance never raises
+    # inside the (rescued) persistence path and silently drops generations.
+    #
+    # @return [String] MD5 hex digest
+    def agent_checksum
+      data = {
+        class: self.class.name,
+        prompt_options: class_options(:prompt_options),
+        embed_options: class_options(:embed_options)
+      }.compact
+      Digest::MD5.hexdigest(data.to_json)
+    end
+
+    # Get manifest fingerprint if agent was built from manifest
+    #
+    # @return [String, nil] Fingerprint or nil
+    def manifest_fingerprint
+      return nil unless self.class.respond_to?(:_manifest) && self.class._manifest
+      self.class._manifest.fingerprint
+    end
+
     private
 
-    # After prompt callback - persists the rendered prompt message to context
+    # Class-level option hash for checksums, or nil when unavailable
+    def class_options(reader)
+      return nil unless self.class.respond_to?(reader)
+
+      self.class.public_send(reader)&.except(:access_token, :api_key)
+    end
+
+    # Marks this generation as resuming one that paused for user input, for a
+    # host that replays a stored conversation itself. Private, like
+    # #resuming_generation?, because every public method on an agent is one
+    # of its actions.
+    #
+    # @example
+    #   before_generation { self.resuming_generation = params[:checkpoint].present? }
+    attr_writer :resuming_generation
+
+    # Returns whether this generation resumes one that paused for user input:
+    # true when `self.resuming_generation = true` was set, or when the agent
+    # defines a public `resuming?` (the framework's resume flag) that returns
+    # true. A resuming generation does not persist its prompt.
+    #
+    # @return [Boolean]
+    def resuming_generation?
+      return true if @resuming_generation
+      return false unless respond_to?(:resuming?)
+
+      resuming? ? true : false
+    end
+
+    # After prompt callback - persists the rendered prompt message to context.
+    # Skipped for a resumed generation, because the generation that paused
+    # already persisted the user turn and the resumed prompt replays it.
     def persist_prompt_to_context
       return unless context
+      return if resuming_generation?
 
       if prompt_options[:messages].present?
         rendered_message = prompt_options[:messages].last
@@ -429,14 +586,29 @@ module SolidAgent
       generation_response
     end
 
-    # Persists the generation response to context
+    # Persists the generation response to context. A response paused for user
+    # input is skipped, because its last message is an unfinished turn. The
+    # response of the generation that resumes it repeats the restored tool
+    # results, so they are persisted with the final answer.
     def persist_generation_to_context
       return unless context && generation_response
 
+      if generation_paused?
+        Rails.logger.info "[SolidAgent] Skipping persistence - generation is awaiting user input"
+        return
+      end
+
+      persist_tool_messages_to_context
+
       begin
         if generation_response.respond_to?(:message) && generation_response.message&.content.present?
-          context.record_generation!(generation_response)
-          Rails.logger.info "[SolidAgent] Persisted generation to context #{context.id}"
+          # Include provenance if the context supports it
+          if context.respond_to?(:record_generation_with_provenance!)
+            context.record_generation_with_provenance!(generation_response, current_provenance)
+          else
+            context.record_generation!(generation_response)
+          end
+          Rails.logger.info "[SolidAgent] Persisted generation to context #{context.id} (#{prompt_checksum[0..7]})"
         else
           Rails.logger.warn "[SolidAgent] Skipping persistence - no message content in response"
         end
@@ -445,5 +617,100 @@ module SolidAgent
         Rails.logger.error e.backtrace.first(5).join("\n")
       end
     end
+
+    def generation_paused?
+      return false unless generation_response.respond_to?(:awaiting_input?)
+
+      generation_response.awaiting_input? ? true : false
+    end
+
+    # Overridable enrichment hook for tool persistence. Executors that run
+    # tools server-side (a platform's execution service, a job) can
+    # override this to return their own invocation records — an array of
+    # hashes with symbol keys :tool_call_id, :name, :arguments and
+    # :duration_ms (all optional) — so persisted tool messages carry the
+    # call's arguments and timing, which provider response messages don't
+    # include. Records are matched to response tool messages by
+    # tool_call_id when both sides have one, otherwise by position.
+    def tool_invocations
+      []
+    end
+
+    # Persists the tool/MCP interaction stream (tool result messages from
+    # the response's message stack) to the context, so conversations show
+    # the full agent <-> tool exchange, not just the final assistant text.
+    #
+    # Requires the context model to expose add_tool_message (the install
+    # generator's AgentContext does); contexts without it are skipped.
+    # Messages are deduped by tool_call_id. A response's stack repeats
+    # earlier turns (a multi-turn conversation's history, a resumed
+    # generation's restored conversation), so a call already on the context
+    # or earlier in the same stack is skipped.
+    def persist_tool_messages_to_context
+      return unless context.respond_to?(:add_tool_message)
+      return unless generation_response.respond_to?(:messages)
+
+      tool_index = -1
+      seen_tool_call_ids = Set.new
+      Array(generation_response.messages).each do |message|
+        next unless message.respond_to?(:role) && message.role.to_s == "tool"
+
+        tool_index += 1
+        tool_call_id = message.respond_to?(:tool_call_id) ? message.tool_call_id : nil
+        if tool_call_id.present?
+          next unless seen_tool_call_ids.add?(tool_call_id.to_s)
+          next if tool_message_persisted?(tool_call_id)
+        end
+
+        invocation = tool_invocation_for(tool_call_id, tool_index)
+        # Provider tool messages often carry no name (Ollama's don't); the
+        # executor's invocation record is the fallback.
+        name = (message.name if message.respond_to?(:name))
+        name = invocation[:name] if !name.present? && invocation
+
+        attributes = {
+          tool_call_id: tool_call_id,
+          tool_name: name,
+          result: (message.content if message.respond_to?(:content))
+        }
+        if invocation && tool_message_details_supported?
+          attributes[:arguments] = invocation[:arguments]
+          attributes[:duration_ms] = invocation[:duration_ms]
+        end
+        context.add_tool_message(**attributes)
+      end
+    rescue => e
+      Rails.logger.error "[SolidAgent] Failed to persist tool messages: #{e.message}"
+    end
+
+    def tool_message_persisted?(tool_call_id)
+      return false unless context.respond_to?(:messages)
+
+      scope = context.messages
+      scope.respond_to?(:exists?) && scope.exists?(role: "tool", tool_call_id: tool_call_id)
+    end
+
+    # Finds the executor invocation record for a response tool message —
+    # by tool_call_id when the record carries one, else by position among
+    # the response's tool messages.
+    def tool_invocation_for(tool_call_id, index)
+      invocations = Array(tool_invocations)
+      return nil if invocations.empty?
+
+      if tool_call_id.present?
+        match = invocations.find { |inv| inv[:tool_call_id] && inv[:tool_call_id].to_s == tool_call_id.to_s }
+        return match if match
+      end
+      invocations[index]
+    end
+
+    # Whether the context's add_tool_message accepts the arguments:/
+    # duration_ms: enrichment keywords (older generated models don't).
+    def tool_message_details_supported?
+      parameters = context.method(:add_tool_message).parameters
+      parameters.any? { |type, param_name| type == :keyrest || ([ :key, :keyreq ].include?(type) && param_name == :arguments) }
+    rescue ::NameError
+      false
+    end
   end
 end

data/lib/solid_agent/has_memory.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# HasMemory gives an agent a persistent, agent-curated summary list — the
+# model decides when to read and write it while interacting with tools,
+# other agents, and users.
+#
+# Memory is scoped to a subject record (any ActiveRecord model) plus a
+# scope name, NOT to the agent class — so a memory written by one agent can
+# be recalled by another operating on the same subject. That makes it a
+# handoff channel: agent A records what it learned/did, agent B picks the
+# subject up and recalls the summary before continuing.
+#
+# The concern is duck-typed against a memory model exposing:
+#   Model.for(memorable, scope:)  -> memory record
+#   memory.remember(content, source_agent:, category:) -> entry
+#   memory.recall(limit:, category:) -> entries (responding to #content)
+# The install generator's AgentMemory implements this contract.
+#
+# @example Give an agent memory tools the model can call
+#   class SupportAgent < ApplicationAgent
+#     include SolidAgent::HasMemory
+#     has_memory
+#
+#     def handle
+#       prompt(message: params[:message], tools: memory_tool_definitions)
+#     end
+#   end
+#
+# @example Handoff between agents sharing a subject
+#   ResearchAgent.with(memorable: project).research.generate_now
+#   # later, a different agent class:
+#   WriterAgent.with(memorable: project).draft.generate_now
+#   # WriterAgent's recall_memory returns ResearchAgent's entries too.
+module SolidAgent
+  module HasMemory
+    extend ActiveSupport::Concern
+
+    DEFAULT_SCOPE = "default"
+
+    # Function-calling schemas (common format) for the two memory tools.
+    # Exposed as a module method so non-agent callers (platform executors,
+    # MCP servers) can reuse the exact same contract.
+    def self.tool_definitions
+      [
+        {
+          name: "save_memory",
+          description: "Persist a short summary note to long-term memory. Use for facts, decisions, task outcomes, or anything a future agent or session should know. Keep each note self-contained.",
+          parameters: {
+            type: "object",
+            properties: {
+              content: { type: "string", description: "The summary note to remember" },
+              category: { type: "string", description: "Optional label, e.g. fact, task, handoff" }
+            },
+            required: [ "content" ]
+          }
+        },
+        {
+          name: "recall_memory",
+          description: "Read back previously saved memory notes for the current subject, most recent first. Use before starting work to pick up prior context or another agent's handoff.",
+          parameters: {
+            type: "object",
+            properties: {
+              category: { type: "string", description: "Only return notes with this label" },
+              limit: { type: "integer", description: "Maximum notes to return (default 20)" }
+            },
+            required: []
+          }
+        }
+      ]
+    end
+
+    included do
+      class_attribute :_memory_config, default: nil
+    end
+
+    class_methods do
+      # Configures memory for this agent.
+      #
+      # @param scope [String, Symbol] memory namespace (default "default")
+      # @param class_name [String] memory model (default "AgentMemory")
+      def has_memory(scope: DEFAULT_SCOPE, class_name: "AgentMemory")
+        self._memory_config = { scope: scope.to_s, class_name: class_name }
+      end
+    end
+
+    # The memory record for the current subject (or nil without a subject).
+    def memory
+      config = self.class._memory_config || { scope: DEFAULT_SCOPE, class_name: "AgentMemory" }
+      subject = memory_subject
+      return nil unless subject
+
+      @memory ||= config[:class_name].constantize.for(subject, scope: config[:scope])
+    end
+
+    # The record memory is attached to. Defaults to params[:memorable],
+    # falling back to the HasContext contextable when present. Override for
+    # custom subjects.
+    def memory_subject
+      return params[:memorable] if respond_to?(:params) && params.is_a?(Hash) && params[:memorable]
+
+      context.contextable if respond_to?(:context) && context.respond_to?(:contextable)
+    rescue StandardError
+      nil
+    end
+
+    def memory_tool_definitions
+      SolidAgent::HasMemory.tool_definitions
+    end
+
+    # Tool implementations — routed here by the provider's tool calls.
+
+    def save_memory(content:, category: nil)
+      return { error: "No memory subject available" } unless memory
+
+      entry = memory.remember(content, source_agent: self.class.name, category: category)
+      { saved: true, id: entry.respond_to?(:id) ? entry.id : nil, content: content }
+    end
+
+    def recall_memory(category: nil, limit: 20)
+      return { error: "No memory subject available" } unless memory
+
+      entries = memory.recall(limit: limit, category: category)
+      {
+        count: entries.size,
+        entries: entries.map do |entry|
+          {
+            content: entry.content,
+            category: (entry.category if entry.respond_to?(:category)),
+            source_agent: (entry.source_agent if entry.respond_to?(:source_agent)),
+            created_at: (entry.created_at.iso8601 if entry.respond_to?(:created_at) && entry.created_at)
+          }.compact
+        end
+      }
+    end
+  end
+end