feat(ruby): persist tools and evolve artifacts across sessions

Author: kulesh

bin/recurgent-tools

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../runtimes/ruby/lib/recurgent"
+
+def usage!
+  warn <<~USAGE
+    Usage:
+      bin/recurgent-tools list-stale [--days N] [--limit N] [--root PATH]
+      bin/recurgent-tools prune [--days N] [--mode archive|delete] [--dry-run|--apply] [--root PATH]
+  USAGE
+  exit 1
+end
+
+command = ARGV.shift
+usage! if command.nil?
+
+options = {
+  days: 30,
+  limit: nil,
+  root: Agent.default_toolstore_root,
+  mode: "archive",
+  dry_run: true
+}
+
+parser = OptionParser.new do |opts|
+  opts.on("--days N", Integer, "stale threshold in days (default: 30)") { |value| options[:days] = value }
+  opts.on("--limit N", Integer, "max rows for list-stale") { |value| options[:limit] = value }
+  opts.on("--root PATH", String, "toolstore root path") { |value| options[:root] = value }
+  opts.on("--mode MODE", String, "prune mode: archive|delete (default: archive)") { |value| options[:mode] = value }
+  opts.on("--dry-run", "preview prune changes (default)") { options[:dry_run] = true }
+  opts.on("--apply", "apply prune changes") { options[:dry_run] = false }
+end
+parser.parse!(ARGV)
+
+maintenance = Agent::ToolMaintenance.new(toolstore_root: options[:root])
+
+case command
+when "list-stale"
+  result = maintenance.list_stale_tools(stale_days: options[:days], limit: options[:limit])
+  puts JSON.pretty_generate(result)
+when "prune"
+  result = maintenance.prune_stale_tools(
+    stale_days: options[:days],
+    dry_run: options[:dry_run],
+    mode: options[:mode]
+  )
+  puts JSON.pretty_generate(result)
+else
+  usage!
+end

runtimes/ruby/lib/recurgent.rb

@@ -12,6 +12,15 @@
 require_relative "recurgent/observability"
 require_relative "recurgent/dependencies"
 require_relative "recurgent/runtime_config"
+require_relative "recurgent/known_tool_ranker"
+require_relative "recurgent/tool_store_paths"
+require_relative "recurgent/tool_store"
+require_relative "recurgent/artifact_metrics"
+require_relative "recurgent/artifact_store"
+require_relative "recurgent/artifact_selector"
+require_relative "recurgent/artifact_repair"
+require_relative "recurgent/persisted_execution"
+require_relative "recurgent/tool_maintenance"
 require_relative "recurgent/call_state"
 require_relative "recurgent/call_execution"
 require_relative "recurgent/worker_executor"
@@ -55,6 +64,10 @@ class Agent
   DEFAULT_DELEGATION_BUDGET = 8
   DEFAULT_GEM_SOURCES = ["https://rubygems.org"].freeze
   DEFAULT_SOURCE_MODE = "public_only"
+  TOOLSTORE_SCHEMA_VERSION = 1
+  PROMPT_VERSION = "2026-02-15.depth-aware.v3"
+  MAX_REPAIRS_BEFORE_REGEN = 3
+  KNOWN_TOOLS_PROMPT_LIMIT = 12
   CALL_STACK_KEY = :__recurgent_call_stack
   OUTCOME_CONTEXT_KEY = :__recurgent_outcome_context
   RUNTIME_NAME = "ruby"
@@ -105,6 +118,14 @@ class BudgetExceededError < Error; end
   include Prompting
   include Observability
   include Dependencies
+  include KnownToolRanker
+  include ToolStorePaths
+  include ToolStore
+  include ArtifactMetrics
+  include ArtifactStore
+  include ArtifactSelector
+  include ArtifactRepair
+  include PersistedExecution
   include CallExecution
   include WorkerExecution
 
@@ -114,6 +135,11 @@ def self.default_log_path
     File.join(state_home, "recurgent", "recurgent.jsonl")
   end
 
+  def self.default_toolstore_root
+    state_home = ENV.fetch("XDG_STATE_HOME", File.join(Dir.home, ".local", "state"))
+    File.join(state_home, "recurgent", "tools")
+  end
+
   def self.for(role, purpose: nil, deliverable: nil, acceptance: nil, failure_policy: nil, delegation_contract: nil, **)
     contract, source = _compose_delegation_contract(
       delegation_contract,
@@ -183,6 +209,8 @@ def initialize(role, **options)
     @prep_ticket_id = nil
     @trace_id = _validate_trace_id(config[:trace_id] || _new_trace_id)
     @log_dir_exists = false
+
+    _hydrate_tool_registry!
   end
 
   # -- The metaprogramming core -----------------------------------------------
@@ -584,6 +612,7 @@ def _register_delegated_tool(role:, tool:, explicit_purpose:)
     metadata.merge!(_delegated_tool_contract_summary(contract))
 
     registry[role_name] = metadata
+    _persist_tool_registry_entry(role_name, metadata)
   end
 
   def _registered_tool_metadata(role_name)

runtimes/ruby/lib/recurgent/artifact_metrics.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class Agent
+  # Agent::ArtifactMetrics — failure classification and artifact health accounting.
+  module ArtifactMetrics
+    EXTRINSIC_FAILURE_TYPES = %w[
+      timeout
+      provider
+      network_error
+      rate_limit
+      rate_limited
+      environment_preparing
+      worker_crash
+      dependency_resolution_failed
+      dependency_install_failed
+      dependency_activation_failed
+    ].freeze
+    ADAPTIVE_FAILURE_TYPES = %w[
+      parse_error
+      parse_failed
+      missing_input
+      invalid_format
+      schema_mismatch
+    ].freeze
+
+    private
+
+    def _artifact_update_metrics!(artifact, state)
+      if state.outcome&.ok?
+        _artifact_increment_success!(artifact)
+      else
+        _artifact_increment_failure!(artifact, state)
+      end
+      _artifact_update_failure_rate!(artifact)
+    end
+
+    def _artifact_increment_success!(artifact)
+      artifact["success_count"] = artifact["success_count"].to_i + 1
+    end
+
+    def _artifact_increment_failure!(artifact, state)
+      artifact["failure_count"] = artifact["failure_count"].to_i + 1
+      failure_class = _artifact_failure_class(state)
+      _artifact_increment_failure_counter!(artifact, failure_class)
+      artifact["last_failure_class"] = failure_class
+      artifact["last_failure_reason"] = state.outcome&.error_message || state.error&.message || "unknown failure"
+    end
+
+    def _artifact_update_failure_rate!(artifact)
+      successes = artifact["success_count"].to_i
+      failures = artifact["failure_count"].to_i
+      total = successes + failures
+      artifact["recent_failure_rate"] = total.zero? ? 0.0 : (failures.to_f / total).round(4)
+    end
+
+    def _artifact_increment_failure_counter!(artifact, failure_class)
+      key = case failure_class
+            when "extrinsic"
+              "extrinsic_failure_count"
+            when "adaptive"
+              "adaptive_failure_count"
+            else
+              "intrinsic_failure_count"
+            end
+      artifact[key] = artifact[key].to_i + 1
+    end
+
+    def _artifact_failure_class(state)
+      _artifact_failure_class_for(outcome: state.outcome, error: state.error)
+    end
+
+    def _artifact_failure_class_for(outcome:, error:)
+      failure_type = outcome&.error_type.to_s
+      return "extrinsic" if EXTRINSIC_FAILURE_TYPES.include?(failure_type)
+      return "adaptive" if ADAPTIVE_FAILURE_TYPES.include?(failure_type)
+      return "intrinsic" unless failure_type.empty?
+
+      return "extrinsic" if error.is_a?(TimeoutError) || error.is_a?(ProviderError)
+
+      "intrinsic"
+    end
+  end
+end

runtimes/ruby/lib/recurgent/artifact_repair.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class Agent
+  # Agent::ArtifactRepair — persisted artifact repair flow with bounded retry budget.
+  module ArtifactRepair
+    private
+
+    def _repair_persisted_artifact(
+      method_name:,
+      args:,
+      kwargs:,
+      persisted_artifact:,
+      failure_class:,
+      failure_message:,
+      state:
+    )
+      return nil unless _toolstore_repair_enabled?
+      return nil unless _artifact_repair_budget_available?(persisted_artifact)
+
+      state.repair_attempted = true
+      repair_user_prompt = _artifact_repair_user_prompt(
+        method_name: method_name,
+        args: args,
+        kwargs: kwargs,
+        persisted_artifact: persisted_artifact,
+        failure_class: failure_class,
+        failure_message: failure_message
+      )
+      repair_system_prompt = _build_system_prompt(call_context: _call_stack.last)
+
+      repaired_program, state.generation_attempt = _generate_program_with_retry(
+        method_name,
+        repair_system_prompt,
+        repair_user_prompt
+      )
+      _capture_generated_program_state!(state, repaired_program)
+      _mark_repaired_program_state!(state, trigger: _repair_trigger_for(failure_class))
+      environment_info = _prepare_dependency_environment!(
+        method_name: method_name,
+        normalized_dependencies: state.normalized_dependencies
+      )
+      _capture_environment_state!(state, environment_info)
+
+      _execute_generated_program(
+        method_name,
+        state.code,
+        args,
+        kwargs,
+        normalized_dependencies: state.normalized_dependencies,
+        environment_info: environment_info,
+        state: state
+      )
+    rescue ProviderError, ExecutionError, WorkerCrashError, NonSerializableResultError,
+           InvalidDependencyManifestError, DependencyManifestIncompatibleError,
+           DependencyPolicyViolationError, DependencyResolutionError,
+           DependencyInstallError, DependencyActivationError => e
+      warn "[AGENT REPAIR #{@role}.#{method_name}] repair attempt failed: #{e.class}: #{e.message}" if @debug
+      nil
+    end
+
+    def _artifact_repair_budget_available?(artifact)
+      repair_count = artifact.fetch("repair_count_since_regen", 0).to_i
+      repair_count < Agent::MAX_REPAIRS_BEFORE_REGEN
+    end
+
+    def _repair_trigger_for(failure_class)
+      case failure_class
+      when "adaptive"
+        "repair:adaptive_failure"
+      when "intrinsic"
+        "repair:intrinsic_failure"
+      else
+        "repair:unknown_failure"
+      end
+    end
+
+    def _artifact_repair_user_prompt(method_name:, args:, kwargs:, persisted_artifact:, failure_class:, failure_message:)
+      <<~PROMPT
+        <repair_invocation>
+        <method>#{method_name}</method>
+        <args>#{args.inspect}</args>
+        <kwargs>#{kwargs.inspect}</kwargs>
+        <failure_class>#{failure_class}</failure_class>
+        <failure_message>#{failure_message}</failure_message>
+        <existing_code>
+        #{persisted_artifact.fetch("code", "")}
+        </existing_code>
+        <artifact_metadata>
+        <prompt_version>#{persisted_artifact["prompt_version"]}</prompt_version>
+        <contract_fingerprint>#{persisted_artifact["contract_fingerprint"]}</contract_fingerprint>
+        </artifact_metadata>
+        </repair_invocation>
+
+        <repair_goal>
+        Repair this existing method implementation. Preserve intent and contract compatibility.
+        Do not invent new capabilities. Ensure returned code executes for the provided args/kwargs.
+        </repair_goal>
+
+        <response_contract>
+        - Return a GeneratedProgram payload with `code` and optional `dependencies`.
+        - Set `result` to the raw domain value, or use `return` in generated code.
+        </response_contract>
+      PROMPT
+    end
+  end
+end

runtimes/ruby/lib/recurgent/artifact_selector.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class Agent
+  # Agent::ArtifactSelector — persisted artifact compatibility and selection policy.
+  module ArtifactSelector
+    private
+
+    def _select_persisted_artifact(method_name, state:)
+      return nil unless _toolstore_enabled? && _toolstore_artifact_read_enabled?
+
+      artifact = _artifact_load(method_name)
+      return nil unless artifact
+      return nil unless _artifact_compatible_for_execution?(artifact)
+      return nil if _artifact_degraded?(artifact)
+
+      state.artifact_prompt_version = artifact["prompt_version"]
+      state.artifact_contract_fingerprint = artifact["contract_fingerprint"]
+      artifact
+    end
+
+    def _artifact_compatible_for_execution?(artifact)
+      return false unless _artifact_runtime_compatible?(artifact)
+      return false unless _artifact_contract_compatible?(artifact)
+
+      _artifact_checksum_valid?(artifact)
+    end
+
+    def _artifact_runtime_compatible?(artifact)
+      runtime_version = artifact["runtime_version"]
+      return true if runtime_version.nil?
+
+      runtime_version.to_s == Agent::VERSION
+    end
+
+    def _artifact_contract_compatible?(artifact)
+      artifact.fetch("contract_fingerprint", "none") == _artifact_contract_fingerprint
+    end
+
+    def _artifact_checksum_valid?(artifact)
+      code = artifact.fetch("code", "").to_s
+      return false if code.strip.empty?
+
+      checksum = artifact["code_checksum"].to_s
+      checksum == _artifact_code_checksum(code)
+    end
+
+    def _artifact_degraded?(artifact)
+      failures = artifact.fetch("failure_count", 0).to_i
+      successes = artifact.fetch("success_count", 0).to_i
+      failure_rate = artifact.fetch("recent_failure_rate", 0.0).to_f
+
+      failures >= 3 && failure_rate > 0.6 && failures > successes
+    end
+  end
+end