reanimator 0.1.0

data/lib/reanimator/agent_profile.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A policy-constrained execution configuration for one provider, model,
+  # sandbox, tool set, and data-handling posture (specification section 02 and
+  # section 08). A profile is what commissioning proves *ready*, *degraded*,
+  # *incompatible*, or *unavailable* - the readiness verdict is set from a
+  # commissioning report, never assumed.
+  class AgentProfile
+    READINESS = %i[unknown ready degraded incompatible unavailable].freeze
+
+    attr_reader :connection, :model, :sandbox, :data_handling, :capabilities
+    attr_accessor :readiness
+
+    def initialize(connection:, model: nil, sandbox: :ephemeral, data_handling: nil,
+      capabilities: [], readiness: :unknown)
+      @connection = connection
+      @model = model || connection.models.first
+      @sandbox = sandbox
+      @data_handling = data_handling || connection.code_egress
+      @capabilities = capabilities
+      @readiness = readiness.to_sym
+      raise UnknownError, "Unknown readiness #{readiness.inspect}." unless READINESS.include?(@readiness)
+    end
+
+    # Builds a profile straight from an adapter, seeding its capabilities.
+    def self.from_adapter(adapter, **overrides)
+      new(connection: adapter.connection, capabilities: adapter.capabilities, **overrides)
+    end
+
+    def supports?(capability) = capabilities.include?(capability.to_sym)
+
+    def provider = connection.provider
+
+    def ready? = readiness == :ready
+
+    # Two profiles share a data-handling policy when their egress posture
+    # matches - the precondition for any context transfer during fallback
+    # (section 08 fallback rules).
+    def same_data_handling?(other)
+      data_handling == other.data_handling
+    end
+
+    def to_h
+      {
+        provider: provider, model: model, sandbox: sandbox,
+        data_handling: data_handling, readiness: readiness
+      }
+    end
+  end
+end

data/lib/reanimator/agents/adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # The contract every coding-agent provider implements (specification
+    # section 08). Keeping this surface tiny is the whole point: swapping
+    # providers must never require redefining acceptance criteria, so an
+    # adapter only ever *enumerates capabilities* and *proposes a repair* - it
+    # does not grade, merge, or decide policy.
+    class Adapter
+      # @return [AgentConnection]
+      attr_reader :connection
+
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # @return [Symbol] provider name
+      def provider = connection.provider
+
+      # @return [Boolean] whether the adapter can actually run right now
+      #   (credentials present and integration available)
+      def available?
+        raise NotImplementedError, "#{self.class} must implement #available?"
+      end
+
+      # @return [Array<Symbol>] the {Capability} values this adapter offers
+      def capabilities
+        raise NotImplementedError, "#{self.class} must implement #capabilities"
+      end
+
+      # @param capability [Symbol]
+      def supports?(capability) = capabilities.include?(capability.to_sym)
+
+      # The provider's code-egress posture, inherited from the connection.
+      def code_egress = connection.code_egress
+
+      # Attempt a repair. Returns an untrusted {Result}; never applies it.
+      # @param task [RepairTask]
+      # @return [Result]
+      def repair(task)
+        raise NotImplementedError, "#{self.class} must implement #repair"
+      end
+
+      # @return [String, nil] why the adapter is unavailable, for reporting
+      def unavailable_reason = nil
+    end
+  end
+end

data/lib/reanimator/agents/capability.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # The capabilities an adapter can declare and a task can require
+    # (specification section 08 commissioning step 1: "enumerate allowed
+    # capabilities"). Tools are capability-scoped and deny-by-default (section
+    # 12), so a task that needs a capability the profile does not offer is
+    # routed elsewhere or refused - never silently attempted.
+    module Capability
+      # Produce a structured remediation plan.
+      PLAN = :plan
+      # Produce a patch (a set of file edits).
+      PATCH = :patch
+      # Edit repository files in a workspace.
+      REPOSITORY_EDIT = :repository_edit
+      # Execute checks in a sandbox.
+      SANDBOX_EXEC = :sandbox_exec
+      # Reach the network (subject to egress policy).
+      NETWORK = :network
+
+      ALL = [PLAN, PATCH, REPOSITORY_EDIT, SANDBOX_EXEC, NETWORK].freeze
+
+      module_function
+
+      def valid?(capability) = ALL.include?(capability.to_sym)
+    end
+  end
+end

data/lib/reanimator/agents/constraints.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # The immutable envelope a repair must stay inside: which paths it may edit,
+    # which are protected, what it may spend, and where code may travel.
+    #
+    # These four values always travel together, so they are one object rather
+    # than a hash handed from caller to caller - and the decision that depends
+    # on them ("may I edit this path?") lives here, with the data, instead of
+    # being re-derived by whoever happens to hold the hash.
+    class Constraints
+      attr_reader :allowed_paths, :protected_paths, :max_cost_usd, :code_egress
+
+      def initialize(allowed_paths: [], protected_paths: [], max_cost_usd: nil, code_egress: nil)
+        @allowed_paths = Array(allowed_paths)
+        @protected_paths = Array(protected_paths)
+        @max_cost_usd = max_cost_usd
+        @code_egress = code_egress
+        freeze
+      end
+
+      # Accepts either a Constraints or the plain Hash shape, so callers may
+      # pass whichever reads better at the call site.
+      #
+      # @param value [Constraints, Hash, nil]
+      # @return [Constraints]
+      def self.from(value)
+        return value if value.is_a?(self)
+
+        hash = value || {}
+        new(
+          allowed_paths: hash[:allowed_paths] || [],
+          protected_paths: hash[:protected_paths] || [],
+          max_cost_usd: hash[:max_cost_usd],
+          code_egress: hash[:code_egress]
+        )
+      end
+
+      # Whether a repository-relative path may be edited: never a protected
+      # path, and inside the allowed set whenever one is declared. Matching is
+      # depth-correct, so a protected `dir/**` cannot be evaded by nesting.
+      def may_edit?(path)
+        return false if SafetyFloor.protects?(path, protected_paths)
+
+        allowed_paths.empty? || allowed_paths.any? { |glob| SafetyFloor.matches?(glob, path) }
+      end
+
+      def to_h
+        {
+          allowed_paths: allowed_paths, protected_paths: protected_paths,
+          max_cost_usd: max_cost_usd, code_egress: code_egress
+        }.compact
+      end
+    end
+  end
+end

data/lib/reanimator/agents/hosted.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # A placeholder for hosted providers (Codex, Claude, Amp). It declares the
+    # capabilities such a provider would offer so routing and reports can reason
+    # about it, but it is honest that no hosted integration ships in this slice:
+    # it reports itself unavailable rather than pretending to run. A real
+    # adapter - potentially backed by the codenamev/agentic orchestrator -
+    # implements #repair by calling its model and returns the same {Result}.
+    class Hosted < Adapter
+      def available? = false
+
+      def capabilities
+        [Capability::PLAN, Capability::PATCH, Capability::REPOSITORY_EDIT,
+          Capability::SANDBOX_EXEC, Capability::NETWORK]
+      end
+
+      def credentialed?
+        ref = connection.credentials_ref
+        ref && !ENV[ref].to_s.empty?
+      end
+
+      def unavailable_reason
+        if credentialed?
+          "Credentials are present, but the #{provider} hosted adapter is not implemented in this version."
+        else
+          "No credentials found#{" (set #{connection.credentials_ref})" if connection.credentials_ref}; " \
+            "connect the #{provider} provider first."
+        end
+      end
+
+      def repair(_task)
+        raise Error, "The #{provider} adapter cannot run a repair: #{unavailable_reason}"
+      end
+    end
+  end
+end

data/lib/reanimator/agents/local.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # The reference local agent: deterministic, no network, always available.
+    # It runs a list of rule-based {Strategies} and proposes the first patch
+    # that matches. Because it never reaches the network and keeps code on the
+    # user's runner, it satisfies the "local" security posture (section 12) and
+    # is the adapter commissioning can always prove end to end.
+    class Local < Adapter
+      DEFAULT_STRATEGIES = [Strategies::ArithmeticFix].freeze
+
+      def initialize(connection, strategies: nil)
+        super(connection)
+        @strategies = strategies || DEFAULT_STRATEGIES.map(&:new)
+      end
+
+      def available? = true
+
+      # Local execution never touches the network by design.
+      def capabilities
+        [Capability::PLAN, Capability::PATCH, Capability::REPOSITORY_EDIT, Capability::SANDBOX_EXEC]
+      end
+
+      def repair(task)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        strategy = @strategies.find { |s| s.applies?(task) }
+
+        if strategy
+          plan, patch = strategy.call(task)
+          Result.new(plan: plan, patch: patch, cost_usd: 0.0,
+            latency_s: elapsed(started), tool_use: [Capability::REPOSITORY_EDIT, Capability::PATCH], network: [])
+        else
+          Result.new(plan: nil, patch: Patch.new, cost_usd: 0.0, latency_s: elapsed(started),
+            message: "No local strategy matched the objective #{task.objective.id.inspect}.")
+        end
+      end
+
+      private
+
+      def elapsed(started)
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(3)
+      end
+    end
+  end
+end

data/lib/reanimator/agents/patch.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Reanimator
+  module Agents
+    # A proposed change expressed as data, not as a mutation the agent performs
+    # itself. Representing a repair as a set of file edits is what lets the
+    # harness - never the agent - apply it into an isolated evaluation
+    # workspace (specification section 09: evaluation runs separately from the
+    # agent workspace). An agent proposes a Patch; Reanimator decides whether
+    # and where to apply it.
+    class Patch
+      # A single file's new contents (or deletion).
+      Edit = Struct.new(:path, :contents, :delete) do
+        def delete? = delete
+      end
+
+      attr_reader :edits
+
+      def initialize(edits = [])
+        @edits = edits
+      end
+
+      def self.write(path, contents)
+        new([Edit.new(path: path, contents: contents, delete: false)])
+      end
+
+      def empty? = edits.empty?
+
+      def paths = edits.map(&:path)
+
+      # Applies the patch beneath a root directory. The harness calls this on a
+      # disposable copy; agents never call it. Refuses to escape the root.
+      #
+      # @param root [String]
+      # @raise [PolicyViolation] when an edit path escapes the root
+      def apply(root)
+        edits.each do |edit|
+          full = File.expand_path(File.join(root, edit.path))
+          unless full.start_with?(File.expand_path(root) + File::SEPARATOR)
+            raise PolicyViolation, "Patch edit #{edit.path.inspect} escapes the workspace root."
+          end
+
+          if edit.delete?
+            File.delete(full) if File.exist?(full)
+          else
+            FileUtils.mkdir_p(File.dirname(full))
+            File.write(full, edit.contents)
+          end
+        end
+        root
+      end
+
+      def to_h
+        {edits: edits.map { |e| {path: e.path, delete: e.delete?} }}
+      end
+    end
+  end
+end

data/lib/reanimator/agents/repair_task.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # The immutable objective handed to an agent for one repair (specification
+    # section 08 fallback rules and section 17 run ledger). Everything here is
+    # frozen: the agent receives the original task, the constraints it may not
+    # exceed, and *verified evidence* - never mutable conclusions it could talk
+    # itself out of. A fallback agent receives this very same object, not the
+    # previous agent's narrative.
+    class RepairTask
+      # @return [AcceptanceCriterion] the failing criterion to satisfy
+      attr_reader :objective
+      # @return [String] absolute path to the agent's isolated workspace copy
+      attr_reader :workspace
+      # @return [Constraints] the immutable envelope this repair must stay
+      #   inside (allowed paths, protected paths, budget, code egress)
+      attr_reader :constraints
+      # @return [Baseline] the verified pre-repair evidence
+      attr_reader :evidence
+
+      def initialize(objective:, workspace:, evidence:, constraints: {})
+        @objective = objective
+        @workspace = workspace
+        @evidence = evidence
+        @constraints = Constraints.from(constraints)
+        freeze
+      end
+
+      # @return [String] a plain-language statement of the goal
+      def goal = objective.claim
+
+      # --- read-only workspace access for adapters -----------------------------
+
+      def read(relative)
+        full = File.join(workspace, relative)
+        File.read(full) if File.file?(full)
+      end
+
+      def glob(pattern)
+        Dir.glob(File.join(workspace, pattern))
+          .map { |absolute| absolute.delete_prefix("#{workspace}/") }
+          .sort
+      end
+
+      # Whether a path is inside the constraints' allowed set (and outside the
+      # protected set). Adapters should honor this; the harness enforces it.
+      def may_edit?(path) = constraints.may_edit?(path)
+    end
+  end
+end

data/lib/reanimator/agents/result.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # What an adapter returns from a repair attempt (specification section 08
+    # commissioning steps 3 and 5, section 17 run ledger). A result is an
+    # untrusted *proposal*: a structured plan, a patch expressed as data, and
+    # the observable cost/latency/tool-use/network the harness records. It is
+    # never a verdict - Reanimator computes pass/fail itself.
+    class Result
+      attr_reader :plan, :patch, :cost_usd, :latency_s, :tool_use, :network, :message
+
+      def initialize(plan: nil, patch: Patch.new, cost_usd: 0.0, latency_s: 0.0,
+        tool_use: [], network: [], message: nil)
+        @plan = plan
+        @patch = patch
+        @cost_usd = cost_usd
+        @latency_s = latency_s
+        @tool_use = tool_use
+        @network = network
+        @message = message
+      end
+
+      # A well-formed repair proposal has both a structured plan and a
+      # non-empty patch (section 08 step 3: "require a structured plan and
+      # patch").
+      def structured? = !plan.to_s.strip.empty? && !patch.empty?
+
+      def to_h
+        {
+          plan: plan,
+          patch: patch.to_h,
+          cost_usd: cost_usd,
+          latency_s: latency_s,
+          tool_use: tool_use,
+          network: network,
+          message: message
+        }.compact
+      end
+    end
+  end
+end

data/lib/reanimator/agents/strategies/arithmetic_fix.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    module Strategies
+      # A narrow but genuine automated fixer: when an addition helper (a method
+      # named add/sum/plus) subtracts its operands, rewrite the subtraction as
+      # an addition. It is intentionally small - its job is to exercise the full
+      # commissioning pipeline (plan, patch, isolated apply, independent
+      # grading) with a real, deterministic repair rather than a stubbed answer.
+      class ArithmeticFix < Base
+        DEF = /def\s+(?:add|sum|plus)\b/
+        SUBTRACTION = /\b([a-z_]\w*)\s*-\s*([a-z_]\w*)\b/
+
+        def applies?(task) = !locate(task).nil?
+
+        def call(task)
+          path, _source, fixed = locate(task)
+          plan = <<~PLAN.strip
+            Objective: #{task.goal}
+            1. Locate the addition helper that is subtracting its operands (#{path}).
+            2. Replace the subtraction with an addition.
+            3. Re-run the failing check to confirm the arithmetic is correct.
+          PLAN
+          [plan, Patch.write(path, fixed)]
+        end
+
+        private
+
+        # Finds the first editable Ruby file whose addition helper subtracts,
+        # returning [path, original, fixed] or nil.
+        def locate(task)
+          task.glob("**/*.rb").each do |relative|
+            next unless task.may_edit?(relative)
+
+            source = task.read(relative)
+            next unless source&.match?(DEF)
+
+            index = source.index(DEF)
+            after = source[index..]
+            next unless after.match?(SUBTRACTION)
+
+            fixed = source[0...index] + after.sub(SUBTRACTION, '\1 + \2')
+            return [relative, source, fixed]
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/agents/strategies/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Agents
+    # Repair strategies for the local, rule-based agent. A "local agent" is a
+    # first-class provider in the specification (section 01: "Support Codex,
+    # Claude, Amp, local agents, and future providers"). Each strategy is a
+    # deterministic, no-network fixer that inspects a workspace and, when it
+    # recognizes a defect, proposes a plan and a patch.
+    module Strategies
+      class Base
+        # @param task [RepairTask]
+        # @return [Boolean] whether this strategy recognizes the defect
+        def applies?(task)
+          raise NotImplementedError, "#{self.class} must implement #applies?"
+        end
+
+        # @param task [RepairTask]
+        # @return [Array(String, Patch)] a plan and a patch
+        def call(task)
+          raise NotImplementedError, "#{self.class} must implement #call"
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/agents.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Coding-agent adapters. The agent is a replaceable life-force adapter
+  # (specification section 08): the repository's definition of life is defined
+  # by its contract, never by whichever provider happens to perform a repair.
+  # Every provider - Codex, Claude, Amp, or a local rule-based agent - speaks
+  # the same {Agents::Adapter} contract, so profiles are portable and the
+  # acceptance criteria never change when the provider does.
+  #
+  # This module is the registry and factory. It ships one fully working adapter
+  # ({Agents::Local}, a deterministic no-network agent) and stubs for hosted
+  # providers that honestly report themselves unavailable until credentials and
+  # a real integration exist.
+  module Agents
+    module_function
+
+    # Built-in adapters keyed by provider name.
+    def registry
+      {
+        local: Local,
+        codex: Hosted,
+        claude: Hosted,
+        amp: Hosted
+      }
+    end
+
+    # Builds an adapter for a connection.
+    # @param connection [AgentConnection]
+    # @return [Agents::Adapter]
+    def for(connection)
+      klass = registry.fetch(connection.provider, Hosted)
+      klass.new(connection)
+    end
+
+    def providers = registry.keys
+  end
+end

data/lib/reanimator/autonomy_level.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # One rung of the autonomy ladder (specification section 11): trust grows one
+  # bounded capability at a time, from read-only observation to narrowly bounded
+  # merge authority. Each rung names the behavior it allows and the GitHub
+  # access it requires, so a permission grant can always be tied to the exact
+  # action it enables.
+  class AutonomyLevel
+    attr_reader :key, :rank, :behavior, :github_access
+
+    def initialize(key:, rank:, behavior:, github_access:)
+      @key = key
+      @rank = rank
+      @behavior = behavior
+      @github_access = github_access
+      freeze
+    end
+
+    def to_sym = key
+
+    # The ladder in ascending order of authority.
+    LADDER = [
+      [:observe, "Inventory, detect drift, and report.", "Metadata and read-only contents."],
+      [:diagnose, "Run sandboxed checks and produce plans.", "Read-only plus ephemeral execution."],
+      [:repair, "Create a bounded patch in an isolated workspace.", "No repository write required until submission."],
+      [:submit, "Create or update a branch and pull request.", "Contents and pull-request write for selected repositories."],
+      [:merge, "Merge explicitly eligible changes through branch rules.", "Merge capability only where GitHub and policy allow."],
+      [:release, "Publish packages or deploy.", "Not part of the initial product promise."]
+    ].each_with_index.each_with_object({}) do |((key, behavior, access), index), all|
+      all[key] = new(key: key, rank: index, behavior: behavior, github_access: access)
+    end.freeze
+
+    def self.fetch(key)
+      LADDER.fetch(key.to_sym) { raise UnknownError, "Unknown autonomy level #{key.inspect}." }
+    end
+
+    # @return [Array<Symbol>] the ladder keys in ascending authority
+    def self.keys = LADDER.keys
+  end
+end