active_harness 0.3.8 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c6df0d88c07312b2546e83f5e69c58d5b3628e4ff31b0885e10a72d032a5a5e
-  data.tar.gz: f2427084db1992f1c0cdcd44c7fe6518cfaa0d348f1d3720ce9fcf78e40783c2
+  metadata.gz: 5549eddee812779586e86bbe67c2e72d077b7770b98421b0a43dbcb6dca7ab00
+  data.tar.gz: 9249bc587c75dfe7f0d5141b311f46ba0dd4b90b308873b31535044bd7f37ef2
 SHA512:
-  metadata.gz: 39575f2575e8dd5d1dc90a512f1d550512d90b57d37d182c10055901c5f15f6bb4a7d425c5a362acacf0be248c237707d0e1362d71d912b2eb449340c20a9ef9
-  data.tar.gz: 41f8adbbb47d9a0e2a17505f470b8a77ffac7f275eb530ee87f3a5f60c3eaa707a6f2610f16f63fc1a73872d75cb02cfad81a0251dd831b685d02fce0f5bad85
+  metadata.gz: 6aebf953bbb38bb9c7f3ea943b2b1f10efefaa7371ba34b8aad0e8f921a42749731af2473723fc870a4581f84cbf364315435ce18d7f5f78809c175de86607dd
+  data.tar.gz: ee32ce687ef93c1616b659ed39ca49e0ac9c98705a7f2768e00bf5ba207cdae92938eaad8012cd8b9bad6413b489419cc7f3c2e3dc6138d8ad5af91dd8bc5ec1

data/lib/active_harness/agent/goal_check.rb

@@ -0,0 +1,26 @@
+module ActiveHarness
+  # Base class for goal checks — the judge of an Agent's final answer.
+  # Subclass it and override #call:
+  #
+  #   class TestsPassedGoal < ActiveHarness::GoalCheck
+  #     def call(candidate:, goal:, state:)
+  #       ok = system("bin/rails test")
+  #       ActiveHarness::GoalCheckResult.new(status: ok ? :achieved : :continue, feedback: "Tests are failing")
+  #     end
+  #   end
+  #
+  #   class DevelopmentAgent < ActiveHarness::Agent
+  #     goal TestsPassedGoal
+  #   end
+  #
+  # The base class exists to fail loudly: forgetting to define #call raises an error
+  # that names the class, instead of an obscure NoMethodError mid-run. It is optional —
+  # any object (or a block) with call(candidate:, goal:, state:) is accepted by `goal`.
+  class GoalCheck
+    def call(candidate:, goal:, state:)
+      raise NotImplementedError,
+            "#{self.class.name || 'GoalCheck'} must define #call(candidate:, goal:, state:) " \
+            "returning an ActiveHarness::GoalCheckResult"
+    end
+  end
+end

data/lib/active_harness/agent/state.rb

@@ -0,0 +1,90 @@
+module ActiveHarness
+  # Intent + verification criteria of one Agent run. Built by +setup+ (a Pipeline);
+  # without +setup+ the runtime makes a minimal Goal from the input.
+  Goal = Struct.new(:task, :constraints, :success_criteria, :plan, keyword_init: true) do
+    def self.from(value)
+      case value
+      when Goal   then value
+      when String then value.strip.empty? ? nil : new(task: value)
+      when Hash
+        h = value.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+        return nil if h[:task].to_s.strip.empty?
+
+        new(task: h[:task], constraints: h[:constraints], success_criteria: h[:success_criteria], plan: h[:plan])
+      end
+    end
+  end
+
+  # What a goal check returns.
+  #
+  #   status   — :achieved | :continue | :replan | :needs_input | :failed
+  #   feedback — text for the model (for :continue / :replan)
+  #   evidence — anything useful for the trace
+  GoalCheckResult = Struct.new(:status, :feedback, :evidence, keyword_init: true) do
+    def self.from(value)
+      case value
+      when GoalCheckResult then value
+      when true            then new(status: :achieved)
+      when false, nil      then new(status: :continue, feedback: "The goal is not reached yet.")
+      when Hash
+        new(status: (value[:status] || value["status"])&.to_sym, feedback: value[:feedback] || value["feedback"], evidence: value[:evidence] || value["evidence"])
+      else
+        raise ArgumentError, "A goal check must return GoalCheckResult (or true/false/Hash), got #{value.class}"
+      end
+    end
+  end
+
+  # One tool call requested by the model, with its outcome.
+  #
+  #   id     — provider call id; the tool message is bound to it
+  #   name   — wire name (os__ls)
+  #   tool   — Tool class (nil for an unknown name)
+  #   input  — validated arguments (symbol keys) or the raw value if invalid
+  #   result — ToolResult
+  ToolCall = Struct.new(:id, :name, :tool, :input, :result, keyword_init: true) do
+    def full_name
+      tool ? tool.full_name : name
+    end
+
+    def denied?
+      !result.nil? && result.status == :denied
+    end
+
+    def error?
+      !result.nil? && result.status == :error
+    end
+  end
+
+  # One iteration of the Agent loop.
+  AgentTurn = Struct.new(:number, :request_name, :request, :response, :tool_calls, :steps, :verdict, :ms, keyword_init: true) do
+    def denied_calls
+      tool_calls.select(&:denied?)
+    end
+
+    def error_calls
+      tool_calls.select(&:error?)
+    end
+  end
+
+  # Trustworthy data of one run — the source of truth. The model-facing context is
+  # only a view built from it by the context builder.
+  #
+  #   messages — normalized conversation (user / assistant / tool)
+  #   events   — full journal of turns, denials, tool calls and results; never summarized
+  AgentState = Struct.new(
+    :run_id, :status, :input, :goal, :plan,
+    :messages, :events, :artifacts,
+    :turn, :tool_calls_count, :usage, :stop_reason,
+    keyword_init: true
+  )
+
+  class Agent
+    # Default context builder: the full history. A custom builder is any object with
+    # call(state:) returning a messages array (a shortened view, never a rewrite of the state).
+    class ContextBuilder
+      def call(state:)
+        state.messages.map(&:dup)
+      end
+    end
+  end
+end