solid_agent 0.1.1 → 0.2.0

data/lib/generators/solid_agent/install/templates/agent_context.rb.erb

@@ -40,31 +40,60 @@ class AgentContext < ApplicationRecord
 
   # Records a generation response and updates token counts
   #
+  # Response attributes are read defensively: ActiveAgent 1.x response
+  # objects don't expose #provider or #duration, and provider messages may
+  # not respond to #tool_calls — a hard read would raise inside
+  # SolidAgent's rescued persistence callback and silently drop the
+  # generation.
+  #
   # @param response [ActiveAgent::GenerationResponse] the generation response
+  # @param extra_attributes [Hash] additional column values (e.g. trace_id, provenance)
   # @return [AgentGeneration] the created generation record
-  def record_generation!(response)
-    generation = generations.create!(
+  def record_generation!(response, extra_attributes = {})
+    usage = response.respond_to?(:usage) ? response.usage : nil
+
+    generation = generations.create!({
       content: response.message&.content,
-      model: response.model,
-      provider: response.provider,
-      finish_reason: response.finish_reason,
-      input_tokens: response.usage&.input_tokens || 0,
-      output_tokens: response.usage&.output_tokens || 0,
+      model: response_value(response, :model),
+      provider: response_value(response, :provider),
+      finish_reason: response_value(response, :finish_reason),
+      input_tokens: usage&.input_tokens || 0,
+      output_tokens: usage&.output_tokens || 0,
+      cached_tokens: response_value(usage, :cached_tokens) || 0,
+      reasoning_tokens: response_value(usage, :reasoning_tokens) || 0,
       tool_calls: extract_tool_calls(response),
-      raw_response: response.raw_response,
-      duration_seconds: response.duration
-    )
+      raw_response: response_value(response, :raw_response),
+      duration_seconds: extract_duration_seconds(response, usage)
+    }.merge(extra_attributes))
 
     # Update cumulative token counts
     increment!(:total_input_tokens, generation.input_tokens)
     increment!(:total_output_tokens, generation.output_tokens)
 
     # Also add assistant message to the conversation
-    add_assistant_message(response.message&.content, tool_calls: generation.tool_calls)
+    add_assistant_message(response.message&.content, metadata: { "tool_calls" => generation.tool_calls })
 
     generation
   end
 
+  # Records a generation together with its provenance snapshot, correlating
+  # it with the distributed trace via provenance[:trace_id].
+  #
+  # Called automatically by SolidAgent::HasContext when this method exists.
+  #
+  # @param response [ActiveAgent::GenerationResponse] the generation response
+  # @param provenance [Hash] provenance hash from HasContext#current_provenance
+  # @return [AgentGeneration] the created generation record
+  def record_generation_with_provenance!(response, provenance)
+    provenance = (provenance || {}).deep_stringify_keys
+
+    record_generation!(
+      response,
+      trace_id: provenance["trace_id"],
+      provenance: provenance
+    )
+  end
+
   # Adds a user message to the context
   #
   # @param content [String] the message content
@@ -97,12 +126,14 @@ class AgentContext < ApplicationRecord
   # @param tool_name [String] the name of the tool
   # @param result [Hash, String] the tool result
   # @return [AgentMessage] the created message
-  def add_tool_message(tool_call_id:, tool_name:, result:)
+  def add_tool_message(tool_call_id:, tool_name:, result:, arguments: nil, duration_ms: nil)
     messages.create!(
       role: "tool",
       tool_call_id: tool_call_id,
       tool_name: tool_name,
       tool_result: result,
+      tool_arguments: arguments.presence || {},
+      metadata: duration_ms ? { "duration_ms" => duration_ms } : {},
       content: result.is_a?(String) ? result : result.to_json
     )
   end
@@ -114,14 +145,26 @@ class AgentContext < ApplicationRecord
 
   private
 
+  def response_value(response, method)
+    response.respond_to?(method) ? response.public_send(method) : nil
+  end
+
+  def extract_duration_seconds(response, usage)
+    return response.duration if response.respond_to?(:duration) && response.duration
+
+    duration_ms = usage.respond_to?(:duration_ms) ? usage.duration_ms : nil
+    duration_ms ? duration_ms / 1000.0 : nil
+  end
+
   def extract_tool_calls(response)
-    return [] unless response.message&.tool_calls.present?
+    message = response.message
+    return [] unless message.respond_to?(:tool_calls) && message.tool_calls.present?
 
-    response.message.tool_calls.map do |tc|
+    message.tool_calls.map do |tc|
       {
-        id: tc.id,
-        name: tc.name,
-        arguments: tc.arguments
+        id: tc.respond_to?(:id) ? tc.id : nil,
+        name: tc.respond_to?(:name) ? tc.name : nil,
+        arguments: tc.respond_to?(:arguments) ? tc.arguments : nil
       }
     end
   end

data/lib/generators/solid_agent/install/templates/agent_generation.rb.erb

@@ -19,6 +19,7 @@ class AgentGeneration < ApplicationRecord
   scope :recent, -> { order(created_at: :desc) }
   scope :by_model, ->(model) { where(model: model) }
   scope :with_tool_calls, -> { where.not(tool_calls: []) }
+  scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
   scope :completed, -> { where(finish_reason: "stop") }
 
   # Returns total token count for this generation
@@ -26,6 +27,16 @@ class AgentGeneration < ApplicationRecord
     input_tokens + output_tokens
   end
 
+  # Provider prompt-cache hit on this generation?
+  def cache_hit?
+    cached_tokens.to_i.positive?
+  end
+
+  # Extended thinking captured?
+  def thinking?
+    reasoning_tokens.to_i.positive?
+  end
+
   # Check if this generation included tool calls
   def has_tool_calls?
     tool_calls.present? && tool_calls.any?
@@ -49,11 +60,17 @@ class AgentGeneration < ApplicationRecord
   # Returns the cost estimate based on token usage (override with your pricing)
   #
   # @param input_price_per_million [Float] price per million input tokens
-  # @param output_price_per_million [Float] price per million output tokens
-  # @return [Float] estimated cost in dollars
-  def estimated_cost(input_price_per_million: 3.0, output_price_per_million: 15.0)
-    input_cost = (input_tokens / 1_000_000.0) * input_price_per_million
-    output_cost = (output_tokens / 1_000_000.0) * output_price_per_million
-    input_cost + output_cost
+  # @param output_price_per_million [Float, nil] price per million output tokens
+  # @return [Float, nil] estimated cost in dollars, nil when nothing to price
+  def estimated_cost(input_price_per_million: nil, output_price_per_million: nil)
+    if input_price_per_million && output_price_per_million
+      input_cost = (input_tokens / 1_000_000.0) * input_price_per_million
+      output_cost = (output_tokens / 1_000_000.0) * output_price_per_million
+      input_cost + output_cost
+    else
+      # Per-model rates from SolidAgent::ModelPricing (RubyLLM registry
+      # when available, static table otherwise)
+      SolidAgent::ModelPricing.estimate(model: model, input_tokens: input_tokens, output_tokens: output_tokens)
+    end
   end
 end

data/lib/generators/solid_agent/install/templates/agent_memory.rb.erb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Agent-curated long-term memory for a subject record, written and read by
+# agents through SolidAgent::HasMemory's save_memory/recall_memory tools.
+#
+# Memory is scoped to (memorable, scope) — not to an agent class — so any
+# agent operating on the same subject shares it, making it a handoff
+# channel between agents. Entry source_agent records who wrote each note.
+class AgentMemory < ApplicationRecord
+  belongs_to :memorable, polymorphic: true, optional: true
+  has_many :entries, class_name: "AgentMemoryEntry", dependent: :destroy
+
+  validates :scope, presence: true
+
+  # Finds or creates the memory for a subject.
+  def self.for(memorable, scope: SolidAgent::HasMemory::DEFAULT_SCOPE)
+    find_or_create_by!(memorable: memorable, scope: scope.to_s)
+  end
+
+  # Appends a summary note.
+  def remember(content, source_agent: nil, category: nil)
+    entries.create!(content: content, source_agent: source_agent, category: category)
+  end
+
+  # Most recent notes first.
+  def recall(limit: 20, category: nil)
+    scope = entries.order(created_at: :desc)
+    scope = scope.where(category: category) if category.present?
+    scope.limit(limit || 20).to_a
+  end
+
+  def forget(entry_id)
+    entries.find(entry_id).destroy!
+  end
+
+  def summary_list
+    entries.order(:created_at).pluck(:content)
+  end
+
+  # Formatted block suitable for injecting into another agent's
+  # instructions when handing a subject off.
+  def to_prompt
+    notes = entries.order(:created_at).map do |entry|
+      source = entry.source_agent.present? ? " (#{entry.source_agent})" : ""
+      "- #{entry.content}#{source}"
+    end
+    return "" if notes.empty?
+
+    "Memory notes for this subject:\n#{notes.join("\n")}"
+  end
+end

data/lib/generators/solid_agent/install/templates/agent_memory_entry.rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# One agent-authored summary note in an AgentMemory.
+class AgentMemoryEntry < ApplicationRecord
+  belongs_to :agent_memory
+
+  validates :content, presence: true
+
+  scope :chronological, -> { order(:created_at) }
+  scope :by_category, ->(category) { where(category: category) }
+  scope :from_agent, ->(agent_name) { where(source_agent: agent_name) }
+end

data/lib/generators/solid_agent/install/templates/agent_run.rb.erb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# A single agent execution: lifecycle status, inputs/outputs, usage, and
+# an append-only stream of progress events. Correlates with AgentContext/
+# AgentGeneration rows and telemetry traces via trace_id.
+class AgentRun < ApplicationRecord
+  belongs_to :runnable, polymorphic: true, optional: true
+
+  STATUSES = %w[pending running complete failed cancelled].freeze
+
+  validates :status, inclusion: { in: STATUSES }
+
+  scope :recent, -> { order(created_at: :desc) }
+  scope :for_agent, ->(agent_name) { where(agent_name: agent_name) }
+  scope :for_action, ->(action_name) { where(action_name: action_name) }
+  scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
+  scope :for_status, ->(status) { where(status: status) }
+
+  STATUSES.each do |status_name|
+    define_method("#{status_name}?") { status == status_name }
+  end
+
+  def in_progress?
+    pending? || running?
+  end
+
+  def finished?
+    complete? || failed? || cancelled?
+  end
+
+  # === Lifecycle ===
+
+  def start!
+    update!(status: "running", started_at: Time.current)
+  end
+
+  def complete!(output: nil, metadata: {}, input_tokens: nil, output_tokens: nil)
+    update!(
+      status: "complete",
+      output: output,
+      output_metadata: (output_metadata || {}).merge(metadata),
+      input_tokens: input_tokens || self.input_tokens,
+      output_tokens: output_tokens || self.output_tokens,
+      completed_at: Time.current,
+      duration_ms: calculated_duration_ms(fallback_end: Time.current)
+    )
+  end
+
+  def fail!(error)
+    update!(
+      status: "failed",
+      error_message: error.respond_to?(:message) ? error.message : error.to_s,
+      completed_at: Time.current,
+      duration_ms: calculated_duration_ms(fallback_end: Time.current)
+    )
+  end
+
+  def cancel!
+    return false if finished?
+
+    update!(status: "cancelled", completed_at: Time.current)
+    true
+  end
+
+  # === Progress events ===
+
+  # Appends a progress event mid-run so pollers can stream what the agent
+  # is doing (pending llm/tool/agent calls). Events pair up by eid: a
+  # "started" event is pending until a "done"/"error" with the same eid
+  # lands. update_column: no validations/callbacks, so this is safe to call
+  # from the run's own execution thread.
+  #
+  # Read-modify-write on a JSON column drops entries when two writers race,
+  # so the re-read and the write are serialized by a row lock.
+  def append_event(kind:, label:, eid: nil, status: "done", detail: nil, duration_ms: nil)
+    event = {
+      "at" => Time.current.iso8601(3),
+      "eid" => eid,
+      "kind" => kind.to_s,
+      "label" => label.to_s,
+      "status" => status.to_s
+    }.compact
+    event["detail"] = detail.to_s.byteslice(0, 1200).to_s.scrub if detail
+    event["duration_ms"] = duration_ms if duration_ms
+
+    with_lock do
+      current = self.class.where(id: id).pick(:events) || []
+      update_column(:events, current + [ event ])
+    end
+
+    event
+  end
+
+  # === Cohort fingerprinting ===
+
+  # Records the instructions this run executed under as a stable digest —
+  # the grouping key (with model) for configuration cohorts.
+  def record_instructions(instructions)
+    self.instructions_digest = SolidAgent::RunFingerprint.digest(instructions)
+  end
+
+  # Deterministic memorable name for the digest ("calm-heron") — reads far
+  # better than hex when comparing cohorts.
+  def instructions_codename
+    SolidAgent::RunFingerprint.codename(instructions_digest)
+  end
+
+  # === Usage ===
+
+  def total_tokens
+    input_tokens.to_i + output_tokens.to_i
+  end
+
+  def calculated_duration_ms(fallback_end: nil)
+    return duration_ms if duration_ms.present?
+
+    finish = completed_at || fallback_end
+    return nil unless started_at && finish
+
+    ((finish - started_at) * 1000).to_i
+  end
+end

data/lib/generators/solid_agent/install/templates/create_agent_generations.rb.erb

@@ -18,6 +18,9 @@ class CreateAgentGenerations < ActiveRecord::Migration<%= migration_version %>
       # Token usage for this generation
       t.integer :input_tokens, default: 0
       t.integer :output_tokens, default: 0
+      # Provider prompt-cache hits and extended-thinking usage
+      t.integer :cached_tokens, default: 0
+      t.integer :reasoning_tokens, default: 0
 
       # Tool calls made in this generation
       t.jsonb :tool_calls, default: []
@@ -28,11 +31,21 @@ class CreateAgentGenerations < ActiveRecord::Migration<%= migration_version %>
       # Timing
       t.float :duration_seconds
 
+      # Telemetry correlation: the distributed trace this generation belongs
+      # to (e.g. ActiveAgent::Telemetry trace_id), threaded through
+      # prompt_options[:trace_id]
+      t.string :trace_id
+
+      # Provenance snapshot (agent/prompt/context checksums) captured at
+      # generation time — see SolidAgent::HasContext#current_provenance
+      t.jsonb :provenance, default: {}
+
       t.timestamps
     end
 
     add_index :agent_generations, :model
     add_index :agent_generations, :finish_reason
+    add_index :agent_generations, :trace_id
     add_index :agent_generations, [:agent_context_id, :created_at]
   end
 end

data/lib/generators/solid_agent/install/templates/create_agent_memories.rb.erb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class CreateAgentMemories < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_memories do |t|
+      # The subject the memory is about (an Agent record, User, Project...).
+      # Any agent operating on the same subject + scope shares the memory,
+      # which is what makes it a handoff channel between agents.
+      t.references :memorable, polymorphic: true, index: true
+
+      # Namespace so a subject can carry independent memory streams.
+      t.string :scope, null: false, default: "default"
+
+      t.timestamps
+    end
+    add_index :agent_memories, [ :memorable_type, :memorable_id, :scope ], unique: true
+
+    create_table :agent_memory_entries do |t|
+      t.references :agent_memory, null: false, foreign_key: true
+
+      # The summary note the agent chose to persist.
+      t.text :content, null: false
+
+      # Which agent class wrote it (handoff provenance).
+      t.string :source_agent
+
+      # Optional label: fact, task, handoff, ...
+      t.string :category
+
+      t.timestamps
+    end
+    add_index :agent_memory_entries, [ :agent_memory_id, :created_at ]
+    add_index :agent_memory_entries, :category
+  end
+end

data/lib/generators/solid_agent/install/templates/create_agent_messages.rb.erb

@@ -23,6 +23,11 @@ class CreateAgentMessages < ActiveRecord::Migration<%= migration_version %>
       # Metadata
       t.jsonb :metadata, default: {}
 
+      # Provenance snapshot + content checksum, populated automatically by
+      # SolidAgent::HasContext when present
+      t.jsonb :provenance, default: {}
+      t.string :content_checksum
+
       t.timestamps
     end
 

data/lib/generators/solid_agent/install/templates/create_agent_runs.rb.erb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class CreateAgentRuns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_runs do |t|
+      # What the run executed against (an Agent record, a workflow, any
+      # AR subject) — optional, so bare executors can still record runs.
+      t.references :runnable, polymorphic: true, index: true
+
+      # Correlation keys shared with agent_contexts/agent_generations and
+      # telemetry traces.
+      t.string :agent_name
+      t.string :action_name
+      t.string :trace_id
+
+      t.string :status, null: false, default: "pending"
+
+      t.text :input_prompt
+      t.jsonb :input_params, default: {}
+      t.text :output
+      t.jsonb :output_metadata, default: {}
+      t.text :error_message
+
+      # Append-only progress events ({at, eid, kind, label, status,
+      # detail, duration_ms}) streamed to pollers mid-run.
+      t.jsonb :events, default: []
+
+      # 8-char fingerprint of the instructions the run executed under —
+      # the cohort grouping key for instruction/model comparisons.
+      t.string :instructions_digest
+
+      t.integer :input_tokens, default: 0
+      t.integer :output_tokens, default: 0
+      t.integer :duration_ms
+      t.datetime :started_at
+      t.datetime :completed_at
+
+      t.timestamps
+    end
+
+    add_index :agent_runs, :status
+    add_index :agent_runs, :trace_id
+    add_index :agent_runs, :instructions_digest
+    add_index :agent_runs, :created_at
+  end
+end

data/lib/generators/solid_agent/manifest/manifest_generator.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SolidAgent
+  module Generators
+    class ManifestGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a .agent.md manifest file for an agent"
+
+      class_option :model, type: :string, default: "anthropic/claude-sonnet-4-20250514",
+        desc: "Model identifier (provider/model format)"
+
+      class_option :tools, type: :array, default: [],
+        desc: "Tool names to include"
+
+      class_option :template, type: :string, default: nil,
+        desc: "Use a preset template (research, assistant, reviewer, chat)"
+
+      class_option :format, type: :string, default: "agent_md",
+        desc: "Output format (agent_md, dotprompt)"
+
+      class_option :context, type: :string, default: nil,
+        desc: "Contextual param key for HasContext (e.g., user, document)"
+
+      class_option :description, type: :string, default: nil,
+        desc: "Agent description"
+
+      def create_manifest_file
+        @model = options[:model]
+        @tools = options[:tools]
+        @preset = options[:template]
+        @format = options[:format].to_sym
+        @contextual = options[:context]
+        @description = options[:description] || default_description
+
+        # Apply preset template configuration
+        apply_preset if @preset
+
+        case @format
+        when :agent_md
+          template "agent.md.erb", manifest_path(".agent.md")
+        when :dotprompt
+          template "prompt.erb", manifest_path(".prompt")
+        else
+          template "agent.md.erb", manifest_path(".agent.md")
+        end
+      end
+
+      def show_next_steps
+        say ""
+        say "Manifest created successfully!", :green
+        say ""
+        say "File generated:"
+        say "  #{manifest_path(extension_for_format)}"
+        say ""
+        say "Usage:", :yellow
+        say "  # Parse the manifest"
+        say "  manifest = SolidAgent::AgentManifest.parse(\"#{manifest_path(extension_for_format)}\")"
+        say ""
+        say "  # Load as agent class"
+        say "  klass = SolidAgent::AgentManifest.load_agent(\"#{manifest_path(extension_for_format)}\")"
+        say ""
+        say "  # Validate the manifest"
+        say "  SolidAgent::AgentManifest.validate!(\"#{manifest_path(extension_for_format)}\")"
+        say ""
+
+        if @tools.any?
+          say "Tool stubs added. Implement the tool methods in your agent class:", :yellow
+          @tools.each do |tool|
+            say "  def #{tool}(args)"
+            say "    # Implement #{tool} logic"
+            say "  end"
+          end
+          say ""
+        end
+      end
+
+      private
+
+      def file_name
+        name.underscore
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def agent_class_name
+        "#{class_name}Agent"
+      end
+
+      def agent_title
+        class_name.gsub(/([A-Z])/, ' \1').strip
+      end
+
+      def manifest_path(extension)
+        "app/views/#{file_name}_agent/agent#{extension}"
+      end
+
+      def extension_for_format
+        case @format
+        when :agent_md then ".agent.md"
+        when :dotprompt then ".prompt"
+        else ".agent.md"
+        end
+      end
+
+      def default_description
+        "#{agent_title} agent"
+      end
+
+      def apply_preset
+        case @preset.to_s
+        when "research"
+          @description ||= "Research and analyze topics thoroughly, providing well-sourced information"
+          @tools = %w[search fetch analyze] if @tools.empty?
+          @preset_instructions = research_instructions
+        when "assistant"
+          @description ||= "General-purpose assistant for answering questions and helping with tasks"
+          @preset_instructions = assistant_instructions
+        when "reviewer"
+          @description ||= "Review and provide feedback on content, code, or documents"
+          @tools = %w[read_file analyze_diff] if @tools.empty?
+          @preset_instructions = reviewer_instructions
+        when "chat"
+          @description ||= "Conversational agent for multi-turn dialogue"
+          @contextual ||= "user"
+          @preset_instructions = chat_instructions
+        end
+      end
+
+      def research_instructions
+        <<~INSTRUCTIONS
+          You are a thorough research assistant. Your goal is to provide accurate,
+          well-sourced information on any topic.
+
+          ## Guidelines
+
+          - Always cite your sources when providing information
+          - Present multiple perspectives when topics are controversial
+          - Acknowledge uncertainty when information is incomplete
+          - Break down complex topics into understandable explanations
+          - Verify facts before presenting them
+        INSTRUCTIONS
+      end
+
+      def assistant_instructions
+        <<~INSTRUCTIONS
+          You are a helpful assistant. Your goal is to assist users with their
+          questions and tasks effectively.
+
+          ## Guidelines
+
+          - Be concise but thorough in your responses
+          - Ask clarifying questions when requests are ambiguous
+          - Provide step-by-step guidance for complex tasks
+          - Offer alternatives when appropriate
+        INSTRUCTIONS
+      end
+
+      def reviewer_instructions
+        <<~INSTRUCTIONS
+          You are a thorough reviewer. Your goal is to provide constructive feedback
+          that helps improve the quality of the work.
+
+          ## Guidelines
+
+          - Focus on both strengths and areas for improvement
+          - Be specific with your feedback
+          - Provide actionable suggestions
+          - Maintain a constructive and respectful tone
+          - Consider the context and goals of the work
+        INSTRUCTIONS
+      end
+
+      def chat_instructions
+        <<~INSTRUCTIONS
+          You are a conversational assistant. Engage in helpful, natural dialogue
+          while maintaining context from previous messages.
+
+          ## Guidelines
+
+          - Remember context from earlier in the conversation
+          - Ask follow-up questions to better understand the user's needs
+          - Be friendly and approachable
+          - Know when to be concise vs. detailed based on the question
+        INSTRUCTIONS
+      end
+
+      def default_instructions
+        @preset_instructions || <<~INSTRUCTIONS
+          You are the #{agent_title} agent.
+
+          ## Instructions
+
+          TODO - Add your agent's instructions here.
+
+          ## Guidelines
+
+          - Be helpful and accurate
+          - Follow the user's instructions carefully
+          - Ask for clarification when needed
+        INSTRUCTIONS
+      end
+    end
+  end
+end