active_harness 0.2.24 → 0.2.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2fe80bd5361b92a9c034f2dae4d069f381620867140dd7242d3a6ba24f3a429
-  data.tar.gz: 6cb9aaa5d2a388f8f79fe5794623fe8f0e49f4e19bffb352089e1069e8a8a6b0
+  metadata.gz: e251d772ac23a015473080cd54ec79dcd1d707b3ca9fa1c8de6132f8152fa873
+  data.tar.gz: 68674b1744f7696cb26cc02a505e60e8c6ae117c7f20a118a2e8102c8f0821f5
 SHA512:
-  metadata.gz: 56050efdb3f23d189fbca002200699b6c98b7419eb5ec428b52ff5e9149065c4fa5d01822c448e632de23ce4bf291c5c50f80207ff46d6aa449bb0d01c5c1ba8
-  data.tar.gz: 0f3b7726fa25f362d2d660c9f5474255da6c45db0ad26b03a24245e7973f64d87cfe78793e7a75fb80014c6a109a0b3ac33df134e65dabde9863d037b6760a1b
+  metadata.gz: 99ef61764b9c6b7564f1064c191cb89780670c7e24966556f3f52e3fa15b631e492c9c29a3ac7f601249db9515afed291fe2e6d6e333f9fb6c2043dbad22dac1
+  data.tar.gz: 8c8609086bc572183398cf20ff0ea2957e8acd8337db9dadfcb8045f1bbdbb7a708b3f3b27273809a717e91196abe4bf272778d521bfa0926338f0df03486e84

data/lib/active_harness/agent/models.rb

@@ -14,7 +14,7 @@ module ActiveHarness
       # Output format for this agent.
       #
       #   format :text   # default — output is returned as-is
-      #   format :json   # output is parsed; result.parsed is a Ruby Hash/Array
+      #   format :json   # output is parsed; result.processed is a Ruby Hash/Array
       def format(type)
         unless %i[text json].include?(type)
           raise ArgumentError, "Unknown format :#{type}. Valid values: :text, :json"

data/lib/active_harness/agent/output_parser.rb

@@ -39,7 +39,7 @@ module ActiveHarness
       begin
         parsed = JSON.parse(clean)
 
-        # :after_parse — return value replaces parsed result stored in Result
+        # :after_parse — return value replaces processed result stored in Result
         transform_hook(:after_parse, parsed)
       rescue JSON::ParserError => e
         # :parse_error — if hook returns non-nil, it is used as fallback value

data/lib/active_harness/agent.rb

@@ -140,13 +140,13 @@ module ActiveHarness
 
     def build_result(response, entry, attempts, elapsed)
       raw    = response[:content]
-      parsed = parse_output(raw)
+      processed = parse_output(raw)
       usage  = response[:usage]
 
       Result.new(
         input:          @input,
         output:         raw,
-        parsed:         parsed,
+        processed:      processed,
         system_prompt:  @system_prompt,
         provider:       entry[:provider],
         model:          entry[:model],

data/lib/active_harness/memory/adapter/{file.rb → json_file.rb}

@@ -4,7 +4,7 @@ require "fileutils"
 module ActiveHarness
   class Memory
     module Adapter
-      # Persists memory as JSON files on disk.
+      # File-backed memory adapter — stores turns as JSON on disk.
       #
       # Each session is stored in one file:
       #   <path>/<session_id>.json                   (no namespace)
@@ -19,21 +19,21 @@ module ActiveHarness
       #   storage_size     — max turns kept in file          (default: 1000)
       #   eviction_percent — % of oldest turns to drop       (default: 10)
       #   on_trim          — Proc called with trimmed turns  (default: nil)
-      class File < Base
-        DEFAULT_PATH             = "storage/ai/memory"
-        DEFAULT_STORAGE_SIZE     = 1000
+      class JsonFile < Base
+        DEFAULT_PATH         = "storage/ai/memory"
+        DEFAULT_STORAGE_SIZE = 1000
         DEFAULT_TRIM_PERCENT = 10
 
         def initialize(opts = {})
-          @path             = opts.fetch(:path, DEFAULT_PATH)
-          @filename_opt     = opts[:filename]
-          @pretty           = opts.fetch(:pretty, false)
-          @compact          = opts.fetch(:compact, false)
-          @encoding         = opts.fetch(:encoding, "UTF-8")
-          @storage_size     = opts.fetch(:storage_size, DEFAULT_STORAGE_SIZE)
+          @path         = opts.fetch(:path, DEFAULT_PATH)
+          @filename_opt = opts[:filename]
+          @pretty       = opts.fetch(:pretty, false)
+          @compact      = opts.fetch(:compact, false)
+          @encoding     = opts.fetch(:encoding, "UTF-8")
+          @storage_size = opts.fetch(:storage_size, DEFAULT_STORAGE_SIZE)
           @trim_percent = opts.fetch(:eviction_percent, DEFAULT_TRIM_PERCENT)
-          @on_trim          = opts[:on_trim]
-          @namespace        = opts[:namespace]
+          @on_trim      = opts[:on_trim]
+          @namespace    = opts[:namespace]
 
           @session_id = nil
           @turns      = []
@@ -55,13 +55,12 @@ module ActiveHarness
         end
 
         def close
-          # File adapter writes immediately on each write, nothing to flush.
+          # Writes immediately on each write — nothing to flush.
         end
 
         def delete
           path = file_path
           ::FileUtils.rm_f(path)
-          # remove parent dir only if it's a namespace dir and now empty
           dir = ::File.dirname(path)
           if @namespace && Dir.exist?(dir) && Dir.empty?(dir)
             Dir.rmdir(dir)
@@ -77,8 +76,6 @@ module ActiveHarness
           name = resolve_filename
           if @namespace
             ::File.join(@path, @session_id.to_s, "#{@namespace}.json")
-          elsif @filename_opt
-            ::File.join(@path, name)
           else
             ::File.join(@path, name)
           end
@@ -100,7 +97,6 @@ module ActiveHarness
           data = JSON.parse(raw, symbolize_names: true)
           turns = Array(data[:turns])
 
-          # Normalise compact format (q/a) to full format (request/response)
           turns.map do |t|
             if t.key?(:q)
               { request: t[:q], response: t[:a] }
@@ -137,5 +133,41 @@ module ActiveHarness
         end
       end
     end
+
+    # Convenience Memory subclass for file-backed storage.
+    #
+    #   file_name:    replaces session_id — may contain slashes to create
+    #                 subdirectories under storage_path, e.g. "users/42/chat"
+    #                 Final file is always <storage_path>/<file_name>.json
+    #   storage_path: base directory (default: "storage/ai/memory")
+    #
+    # Path traversal is rejected: segments equal to "." or ".." or containing
+    # null bytes raise ArgumentError before any file I/O happens.
+    # Missing directories are created automatically on the first write.
+    class JsonFile < Memory
+      def initialize(file_name:, storage_path: Adapter::JsonFile::DEFAULT_PATH, **opts)
+        super(
+          session_id: sanitize!(file_name),
+          adapter:    Adapter::JsonFile.new(opts.merge(path: storage_path)),
+          **opts
+        )
+      end
+
+      private
+
+      def sanitize!(raw)
+        parts = raw.to_s.split("/").map(&:strip).reject(&:empty?)
+        raise ArgumentError, "file_name must not be empty" if parts.empty?
+
+        parts.each do |part|
+          if part == ".." || part == "." || part.include?("\0")
+            raise ArgumentError, "Invalid file_name segment: #{part.inspect}"
+          end
+        end
+
+        parts.last.sub!(/\.json\z/i, "")
+        parts.join("/")
+      end
+    end
   end
 end

data/lib/active_harness/memory/adapter/postgresql.rb

@@ -0,0 +1,212 @@
+require "json"
+
+module ActiveHarness
+  class Memory
+    module Adapter
+      # PostgreSQL-backed memory adapter.
+      #
+      # Requires the 'pg' gem — add it to your Gemfile yourself:
+      #   gem 'pg'
+      #
+      # Connection options (one of):
+      #   connection:  — a PG::Connection instance you manage
+      #   url:         — connection string; adapter opens and closes the connection
+      #   host:, port:, dbname:, user:, password: — adapter opens and closes the connection
+      #
+      # Storage options:
+      #   table_name:      — default "active_harness_memory_turns"
+      #   storage_size:    — max turns per session kept in the table (default 1000)
+      #   eviction_percent — % of oldest turns to drop when limit is hit (default 10)
+      #   on_trim:         — Proc called with evicted turns
+      #   namespace:       — isolates turns within a session
+      class Postgresql < Base
+        DEFAULT_TABLE        = "active_harness_memory_turns"
+        DEFAULT_STORAGE_SIZE = 1000
+        DEFAULT_TRIM_PERCENT = 10
+
+        TABLE_NAME_RE = /\A[a-zA-Z_][a-zA-Z0-9_.]*\z/
+
+        def initialize(opts = {})
+          @table        = opts.fetch(:table_name, DEFAULT_TABLE).to_s
+          @storage_size = opts.fetch(:storage_size, DEFAULT_STORAGE_SIZE)
+          @trim_percent = opts.fetch(:eviction_percent, DEFAULT_TRIM_PERCENT)
+          @on_trim      = opts[:on_trim]
+          @namespace    = opts[:namespace]
+
+          unless @table.match?(TABLE_NAME_RE)
+            raise ArgumentError, "Invalid table_name: #{@table.inspect}"
+          end
+
+          # Connection source — one of: instance, url, keyword args.
+          @borrowed_conn = opts[:connection]
+          @conn_url      = opts[:url]
+          @conn_kwargs   = opts.slice(:host, :port, :dbname, :user, :password)
+
+          @owned_conn  = nil
+          @session_id  = nil
+          @turns       = []
+        end
+
+        def open(session_id)
+          @session_id = session_id
+          ensure_connection!
+          @turns = fetch_turns
+        end
+
+        def read
+          @turns.dup
+        end
+
+        def write(turn)
+          insert_turn(turn)
+          @turns << turn
+          trim_if_needed!
+        end
+
+        def close
+          if @owned_conn
+            @owned_conn.close rescue nil
+            @owned_conn = nil
+          end
+        end
+
+        def delete
+          conn.exec_params(
+            "DELETE FROM #{@table} " \
+            "WHERE session_id = $1 AND (namespace IS NOT DISTINCT FROM $2)",
+            [@session_id, @namespace]
+          )
+          @turns = []
+        end
+
+        # -----------------------------------------------------------------------
+        private
+        # -----------------------------------------------------------------------
+
+        def conn
+          @borrowed_conn || @owned_conn ||
+            raise("PostgreSQL connection not open — call open(session_id) first")
+        end
+
+        def ensure_connection!
+          return if @borrowed_conn || @owned_conn
+
+          load_pg!
+
+          @owned_conn =
+            if @conn_url
+              PG.connect(@conn_url)
+            elsif @conn_kwargs.any?
+              PG.connect(**@conn_kwargs)
+            else
+              raise ArgumentError,
+                "PostgreSQL adapter requires one of: connection:, url:, " \
+                "or connection keyword args (host:, port:, dbname:, user:, password:)"
+            end
+        end
+
+        def load_pg!
+          require "pg"
+        rescue LoadError
+          raise LoadError,
+            "The 'pg' gem is required for the PostgreSQL memory adapter. " \
+            "Add it to your Gemfile:  gem 'pg'"
+        end
+
+        def fetch_turns
+          result = conn.exec_params(
+            "SELECT request, response, meta " \
+            "FROM #{@table} " \
+            "WHERE session_id = $1 AND (namespace IS NOT DISTINCT FROM $2) " \
+            "ORDER BY id ASC",
+            [@session_id, @namespace]
+          )
+
+          result.map do |row|
+            turn = { request: row["request"], response: row["response"] }
+            meta = JSON.parse(row["meta"] || "{}", symbolize_names: true)
+            meta.empty? ? turn : turn.merge(meta)
+          end
+        end
+
+        def insert_turn(turn)
+          meta = turn.reject { |k, _| k == :request || k == :response }
+
+          conn.exec_params(
+            "INSERT INTO #{@table} (session_id, namespace, request, response, meta) " \
+            "VALUES ($1, $2, $3, $4, $5::jsonb)",
+            [
+              @session_id,
+              @namespace,
+              turn[:request].to_s,
+              turn[:response].to_s,
+              JSON.generate(meta)
+            ]
+          )
+        end
+
+        def trim_if_needed!
+          return unless @storage_size
+          return if @turns.size <= @storage_size
+
+          to_delete = [@turns.size * @trim_percent / 100, 1].max
+
+          if @on_trim
+            trimmed = @turns.first(to_delete)
+            @on_trim.call(trimmed)
+          end
+
+          conn.exec_params(
+            "DELETE FROM #{@table} WHERE id IN (" \
+            "  SELECT id FROM #{@table} " \
+            "  WHERE session_id = $1 AND (namespace IS NOT DISTINCT FROM $2) " \
+            "  ORDER BY id ASC LIMIT $3" \
+            ")",
+            [@session_id, @namespace, to_delete]
+          )
+
+          @turns.shift(to_delete)
+        end
+      end
+    end
+
+    # Convenience Memory subclass for PostgreSQL-backed storage.
+    #
+    # Requires the 'pg' gem installed by the application:
+    #   gem 'pg'
+    #
+    # Usage — plain Ruby (adapter owns the connection):
+    #   mem = ActiveHarness::Memory::Postgresql.new(
+    #     session_id: "user_42",
+    #     url:        ENV["DATABASE_URL"],
+    #     depth:      10
+    #   )
+    #   mem.load
+    #   # ... use ...
+    #   mem.close
+    #
+    # Usage — Rails (borrow the AR raw connection):
+    #   mem = ActiveHarness::Memory::Postgresql.new(
+    #     session_id: "user_42",
+    #     connection: ActiveRecord::Base.connection.raw_connection
+    #   )
+    class Postgresql < Memory
+      def initialize(session_id:, namespace: nil, on_trim: nil, **opts)
+        mem_keys = %i[depth enabled read_only async]
+        mem_opts = opts.slice(*mem_keys)
+        pg_opts  = opts.reject { |k, _| mem_keys.include?(k) }
+
+        pg_opts[:namespace] = namespace if namespace
+        pg_opts[:on_trim]   = on_trim   if on_trim
+
+        super(
+          session_id: session_id,
+          adapter:    Adapter::Postgresql.new(pg_opts),
+          namespace:  namespace,
+          on_trim:    on_trim,
+          **mem_opts
+        )
+      end
+    end
+  end
+end

data/lib/active_harness/memory/adapter/sqlite.rb

@@ -0,0 +1,233 @@
+require "json"
+
+module ActiveHarness
+  class Memory
+    module Adapter
+      # SQLite-backed memory adapter.
+      #
+      # Requires the 'sqlite3' gem — add it to your Gemfile yourself:
+      #   gem 'sqlite3'
+      #
+      # Connection options (one of):
+      #   database:   — path to the SQLite file; adapter opens and closes the connection
+      #               use ":memory:" for an in-process, non-persistent database
+      #   connection: — an existing SQLite3::Database instance you manage
+      #
+      # Storage options:
+      #   table_name:      — default "active_harness_memory_turns"
+      #   storage_size:    — max turns per session kept in the table (default 1000)
+      #   eviction_percent — % of oldest turns to drop when limit is hit (default 10)
+      #   on_trim:         — Proc called with evicted turns
+      #   namespace:       — isolates turns within a session
+      class Sqlite < Base
+        DEFAULT_TABLE        = "active_harness_memory_turns"
+        DEFAULT_STORAGE_SIZE = 1000
+        DEFAULT_TRIM_PERCENT = 10
+
+        TABLE_NAME_RE = /\A[a-zA-Z_][a-zA-Z0-9_.]*\z/
+
+        def initialize(opts = {})
+          @table        = opts.fetch(:table_name, DEFAULT_TABLE).to_s
+          @storage_size = opts.fetch(:storage_size, DEFAULT_STORAGE_SIZE)
+          @trim_percent = opts.fetch(:eviction_percent, DEFAULT_TRIM_PERCENT)
+          @on_trim      = opts[:on_trim]
+          @namespace    = opts[:namespace]
+
+          unless @table.match?(TABLE_NAME_RE)
+            raise ArgumentError, "Invalid table_name: #{@table.inspect}"
+          end
+
+          @borrowed_conn = opts[:connection]
+          @db_path       = opts[:database]
+          @owned_conn    = nil
+          @session_id    = nil
+          @turns         = []
+        end
+
+        def open(session_id)
+          @session_id = session_id
+          ensure_connection!
+          @turns = fetch_turns
+        end
+
+        def read
+          @turns.dup
+        end
+
+        def write(turn)
+          insert_turn(turn)
+          @turns << turn
+          trim_if_needed!
+        end
+
+        def close
+          if @owned_conn
+            @owned_conn.close rescue nil
+            @owned_conn = nil
+          end
+        end
+
+        def delete
+          db.execute(
+            "DELETE FROM #{@table} WHERE session_id = ? AND (namespace IS ?)",
+            [@session_id, @namespace]
+          )
+          @turns = []
+        end
+
+        # -----------------------------------------------------------------------
+        private
+        # -----------------------------------------------------------------------
+
+        def db
+          @borrowed_conn || @owned_conn ||
+            raise("SQLite connection not open — call open(session_id) first")
+        end
+
+        def ensure_connection!
+          return if @borrowed_conn || @owned_conn
+
+          load_sqlite3!
+
+          unless @db_path
+            raise ArgumentError,
+              "SQLite adapter requires database: (file path or ':memory:')"
+          end
+
+          conn = SQLite3::Database.new(@db_path)
+          conn.execute("PRAGMA journal_mode=WAL")
+          @owned_conn = conn
+        end
+
+        def load_sqlite3!
+          require "sqlite3"
+        rescue LoadError
+          raise LoadError,
+            "The 'sqlite3' gem is required for the SQLite memory adapter. " \
+            "Add it to your Gemfile:  gem 'sqlite3'"
+        end
+
+        def fetch_turns
+          rows = db.execute(
+            "SELECT request, response, meta " \
+            "FROM #{@table} " \
+            "WHERE session_id = ? AND (namespace IS ?) " \
+            "ORDER BY id ASC",
+            [@session_id, @namespace]
+          )
+          rows.map do |row|
+            # row is Array (default) or Hash (results_as_hash=true) — handle both
+            req, resp, meta_str =
+              row.is_a?(Hash) ? row.values_at("request", "response", "meta") : row
+            turn = { request: req, response: resp }
+            meta = JSON.parse(meta_str || "{}", symbolize_names: true)
+            meta.empty? ? turn : turn.merge(meta)
+          end
+        end
+
+        def insert_turn(turn)
+          meta = turn.reject { |k, _| k == :request || k == :response }
+          db.execute(
+            "INSERT INTO #{@table} (session_id, namespace, request, response, meta) " \
+            "VALUES (?, ?, ?, ?, ?)",
+            [
+              @session_id,
+              @namespace,
+              turn[:request].to_s,
+              turn[:response].to_s,
+              JSON.generate(meta)
+            ]
+          )
+        end
+
+        def trim_if_needed!
+          return unless @storage_size
+          return if @turns.size <= @storage_size
+
+          to_delete = [@turns.size * @trim_percent / 100, 1].max
+
+          if @on_trim
+            trimmed = @turns.first(to_delete)
+            @on_trim.call(trimmed)
+          end
+
+          db.execute(
+            "DELETE FROM #{@table} WHERE id IN (" \
+            "  SELECT id FROM #{@table} " \
+            "  WHERE session_id = ? AND (namespace IS ?) " \
+            "  ORDER BY id ASC LIMIT ?" \
+            ")",
+            [@session_id, @namespace, to_delete]
+          )
+
+          @turns.shift(to_delete)
+        end
+      end
+    end
+
+    # Convenience Memory subclass for SQLite-backed storage.
+    #
+    # Usage — plain Ruby (adapter owns the connection):
+    #   mem = ActiveHarness::Memory::Sqlite.new(
+    #     session_id: "user_42",
+    #     database:   "storage/ai/memory.sqlite3",
+    #     depth:      10
+    #   )
+    #   mem.load
+    #   # ... use ...
+    #   mem.close
+    #
+    # Usage — Rails (borrow AR raw connection for SQLite3 adapter):
+    #   mem = ActiveHarness::Memory::Sqlite.new(
+    #     session_id: "user_42",
+    #     connection: ActiveRecord::Base.connection.raw_connection
+    #   )
+    #
+    # Plain Ruby schema setup (run once before first use):
+    #   ActiveHarness::Memory::Sqlite.create_schema!("storage/ai/memory.sqlite3")
+    class Sqlite < Memory
+      # SQL to create the schema — run once before first use in plain Ruby.
+      SCHEMA_SQL = <<~SQL.freeze
+        CREATE TABLE IF NOT EXISTS active_harness_memory_turns (
+          id         INTEGER  PRIMARY KEY AUTOINCREMENT,
+          session_id TEXT     NOT NULL,
+          namespace  TEXT,
+          request    TEXT     NOT NULL,
+          response   TEXT     NOT NULL,
+          meta       TEXT     NOT NULL DEFAULT '{}',
+          created_at TEXT     NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_ah_memory_turns_session
+          ON active_harness_memory_turns (session_id, namespace, id);
+      SQL
+
+      # Create the schema on an existing database or a file path.
+      # Safe to call multiple times — uses CREATE TABLE IF NOT EXISTS.
+      def self.create_schema!(db_or_path)
+        require "sqlite3"
+        conn = db_or_path.is_a?(String) ? SQLite3::Database.new(db_or_path) : db_or_path
+        SCHEMA_SQL.split(";").map(&:strip).reject(&:empty?).each { |sql| conn.execute(sql) }
+      rescue LoadError
+        raise LoadError,
+          "The 'sqlite3' gem is required. Add it to your Gemfile:  gem 'sqlite3'"
+      end
+
+      def initialize(session_id:, namespace: nil, on_trim: nil, **opts)
+        mem_keys = %i[depth enabled read_only async]
+        mem_opts = opts.slice(*mem_keys)
+        sq_opts  = opts.reject { |k, _| mem_keys.include?(k) }
+
+        sq_opts[:namespace] = namespace if namespace
+        sq_opts[:on_trim]   = on_trim   if on_trim
+
+        super(
+          session_id: session_id,
+          adapter:    Adapter::Sqlite.new(sq_opts),
+          namespace:  namespace,
+          on_trim:    on_trim,
+          **mem_opts
+        )
+      end
+    end
+  end
+end

data/lib/active_harness/memory.rb

@@ -1,6 +1,7 @@
 require_relative "memory/adapter/base"
-require_relative "memory/adapter/file"
-require_relative "memory/json_file"
+require_relative "memory/adapter/json_file"
+require_relative "memory/adapter/postgresql"
+require_relative "memory/adapter/sqlite"
 
 module ActiveHarness
   # Conversational memory for agents.
@@ -55,7 +56,7 @@ module ActiveHarness
   #
   class Memory
     ADAPTERS = {
-      file: ->(**opts) { Adapter::File.new(**opts) }
+      json_file: ->(**opts) { Adapter::JsonFile.new(**opts) }
     }.freeze
 
     attr_reader :session_id
@@ -65,7 +66,7 @@ module ActiveHarness
     # -------------------------------------------------------------------------
     #   session_id       — required; uniquely identifies this conversation
     #   depth            — how many past turns to inject into messages (nil = all)
-    #   adapter          — :file (default), or an adapter instance
+    #   adapter          — :json_file (default), or an adapter instance
     #   enabled          — false disables all reads and writes (no-op mode)
     #   read_only        — true: load history but never write new turns
     #   namespace        — isolates history per-agent within a session
@@ -75,7 +76,7 @@ module ActiveHarness
     def initialize(
       session_id:,
       depth:       nil,
-      adapter:     :file,
+      adapter:     :json_file,
       enabled:     true,
       read_only:   false,
       namespace:   nil,

data/lib/active_harness/pipeline/README.md

@@ -0,0 +1,252 @@
+# Pipeline
+
+A pipeline chains multiple agents and tribunals into a sequential workflow.
+Each step receives the current payload, can transform it, and can stop the pipeline early.
+
+## Basic usage
+
+```ruby
+class SupportPipeline < ActiveHarness::Pipeline
+  step :translate, TranslationAgent
+
+  step :injection_guard do
+    use InjectionGuardAgent
+    stop_if ->(result) { result.processed["detected"] == true }
+  end
+
+  step :safety_tribunal do
+    use SafetyTribunal
+    stop_if ->(result) { result.verdict == false }
+  end
+end
+
+pipeline = SupportPipeline.new(input: "Hello", context: { user_id: 1 })
+pipeline.call
+
+pipeline.output       # => final payload string (nil if stopped)
+pipeline.stopped?     # => false
+pipeline.step_results # => { translate: <Result>, injection_guard: <Result>, ... }
+```
+
+## Step types
+
+There are two kinds of classes a step can use.
+
+**Agent step** — runs the agent, takes `result.output` as the new payload:
+
+```ruby
+step :translate, TranslationAgent
+```
+
+**Tribunal step** — runs the tribunal, returns a `Result` with `processed["verdict"]`.
+Payload is never updated by a tribunal step (it always has `stop_if`):
+
+```ruby
+step :safety_tribunal do
+  use SafetyTribunal
+  stop_if ->(result) { result.processed["verdict"] == false }
+end
+```
+
+## Payload propagation
+
+The payload starts as the value passed to `input:` and flows through the steps:
+
+| Condition | Payload after step |
+|-----------|--------------------|
+| Agent step, no `stop_if` | Updated to `result.output` |
+| Agent step with `stop_if` | Unchanged (guard step) |
+| Tribunal step | Unchanged |
+
+After each step the result is also stored in `context[step_name]`,
+so later steps can read earlier results via `@context[:translate]` etc.
+
+## Stopping the pipeline
+
+Any step can stop the pipeline by defining `stop_if`:
+
+```ruby
+step :injection_guard do
+  use InjectionGuardAgent
+  stop_if ->(result) { result.processed["detected"] == true }
+end
+```
+
+When the condition is true:
+- remaining steps are skipped
+- `pipeline.stopped?` returns `true`
+- `pipeline.stopped_at` holds the step name
+- `pipeline.output` is `nil`
+
+## Events and hooks
+
+```ruby
+class SupportPipeline < ActiveHarness::Pipeline
+  on_agent_event    do |event, result|  ... end  # fires for every agent inside
+  on_tribunal_event do |event, verdict| ... end  # fires for every tribunal inside
+  on_pipeline_event do |event, *args|   ... end  # :before_step, :after_step, :stopped, :complete
+end
+```
+
+Runtime streams can be passed at construction time:
+
+```ruby
+SupportPipeline.new(
+  input:   "...",
+  streams: { token: token_lambda, agent: agent_lambda }
+)
+```
+
+## Memory
+
+A memory object can be attached to the pipeline. It is loaded before the first step
+and a record is written after successful completion (skipped if the pipeline stops early):
+
+```ruby
+mem = ActiveHarness::Memory::JsonFile.new(file_name: "session_42")
+
+SupportPipeline.new(input: "...", memory: mem).call
+```
+
+---
+
+## Proposal: universal step interface
+
+Currently `Pipeline::Step` special-cases two concrete classes: `Agent` and `Tribunal`.
+This section explores making the pipeline open to any entity — a plain Ruby object,
+a lambda, a nested pipeline, an HTTP call, a cache lookup — with no inheritance required.
+
+The core question is: **what must a step return so the pipeline can drive it?**
+
+---
+
+### Option A — Duck-type protocol (minimal change)
+
+Define a lightweight protocol. Any object that satisfies it can be a step:
+
+```ruby
+# Contract: class responds to .new(input:, context:, params:, streams:)
+# Instance responds to .call → returns an object with:
+#   .output  — new payload (String or any value); nil keeps payload unchanged
+#   .stop?   — true signals the pipeline to halt (replaces stop_if in step DSL)
+
+class UppercaseStep
+  def initialize(input:, **); @input = input; end
+
+  def call
+    Pipeline::StepResult.new(output: @input.upcase)
+  end
+end
+
+step :upcase, UppercaseStep
+```
+
+`Pipeline::StepResult` would be a tiny value object:
+
+```ruby
+Pipeline::StepResult = Struct.new(:output, :stop, keyword_init: true) do
+  def stop? = stop
+end
+```
+
+**Pros:** almost no change to existing code; agents and tribunals get thin adapters.  
+**Cons:** every custom step must construct `StepResult`; slightly more boilerplate.
+
+---
+
+### Option B — Callable (lambda / proc) as a step
+
+Allow any `Proc`/`lambda` directly, without a wrapper class:
+
+```ruby
+step :sanitize, ->(payload, ctx) { payload.strip }
+
+step :length_guard, ->(payload, ctx) {
+  payload.length > 1000 ? Pipeline::Stop : payload
+}
+```
+
+Return value rules:
+- any value other than `Pipeline::Stop` → becomes new payload
+- `Pipeline::Stop` (or `Pipeline::Stop.new(reason)`) → halts the pipeline
+
+**Pros:** perfect for simple transformations and guards; zero boilerplate.  
+**Cons:** no access to `params:` or `streams:` without enlarging the lambda signature;
+harder to test in isolation.
+
+---
+
+### Option C — Rack-style env hash
+
+Each step receives and returns a single hash (`env`), similar to Rack middleware:
+
+```ruby
+# env keys: :input, :output, :context, :params, :streams
+# Return env to continue, return Pipeline::Stop to halt.
+
+class UppercaseStep
+  def call(env)
+    env.merge(output: env[:input].upcase)
+  end
+end
+
+class LengthGuard
+  def call(env)
+    env[:input].length > 1000 ? Pipeline::Stop.new("too long") : env
+  end
+end
+```
+
+Steps become stateless (no `initialize`) — a single instance can be reused:
+
+```ruby
+UPCASE = UppercaseStep.new
+
+step :upcase,       UPCASE
+step :length_guard, LengthGuard.new
+```
+
+**Pros:** stateless, composable, easy to test (`call(env)` in one line); nested
+pipelines become trivial — a pipeline is just another object with `call(env)`.  
+**Cons:** largest departure from the current API; requires migrating Agent/Tribunal wrappers.
+
+---
+
+### Option D — `Pipeline::Callable` module (explicit contract)
+
+A module that documents the contract and provides `StepResult` helpers:
+
+```ruby
+class EnrichStep
+  include ActiveHarness::Pipeline::Callable  # documents intent, no magic
+
+  def initialize(input:, context:, **); @input = input; @context = context; end
+
+  def call
+    data = ExternalService.fetch(@context[:user_id])
+    result(output: "#{@input} [enriched: #{data}]")  # helper from Callable
+  end
+end
+```
+
+Agents and Tribunals include `Callable` automatically, so they work as before.
+Any plain class can opt in with one `include`.
+
+**Pros:** clear opt-in contract; helpers reduce boilerplate; IDE-friendly.  
+**Cons:** still requires `include`; doesn't help lambdas or nested pipelines directly.
+
+---
+
+### Comparison
+
+| | No inheritance | Lambda support | Nested pipeline | Migration cost |
+|---|---|---|---|---|
+| **A — duck type** | yes | with wrapper | yes | low |
+| **B — lambda** | yes | native | no | low |
+| **C — Rack env** | yes | yes (`.call`) | yes (trivially) | high |
+| **D — module** | yes (opt-in) | with wrapper | yes | low |
+
+**Recommendation:** start with **B** (lambda steps) for simple cases and **A** (duck-type
+protocol + `StepResult`) for structured steps — both require minimal changes to the
+existing engine. Option C is the most powerful but is a bigger refactor; consider it
+if nested pipelines or stateless reuse become a real need.

data/lib/active_harness/pipeline.rb

@@ -7,7 +7,7 @@ module ActiveHarness
   #   class SupportPipeline < ActiveHarness::Pipeline
   #     step :injection_guard do
   #       use InjectionGuardAgent
-  #       stop_if ->(result) { result.parsed["detected"] == true }
+  #       stop_if ->(result) { result.processed["detected"] == true }
   #     end
   #
   #     step :translate, TranslationAgent   # shorthand — no stop_if
@@ -44,7 +44,7 @@ module ActiveHarness
       # Full block form:
       #   step :injection_guard do
       #     use InjectionGuardAgent
-      #     stop_if ->(result) { result.parsed["detected"] == true }
+      #     stop_if ->(result) { result.processed["detected"] == true }
       #   end
       def step(name, agent_class = nil, &block)
         pipeline_config[:steps] << Pipeline::Step.new(name, agent_class, &block)
@@ -210,23 +210,13 @@ module ActiveHarness
     end
 
     def execute_step(step)
-      if step.tribunal?
-        agent_streams = { token: @token_stream, agent: @agent_event_stream, tribunal: @tribunal_event_stream }.compact
-        step.agent_class.new(
-          input:    @payload,
-          context:  @context.dup,
-          params:   @params,
-          streams:  agent_streams
-        ).call
-      else
-        agent_streams = { token: @token_stream, agent: @agent_event_stream }.compact
-        step.agent_class.new(
-          input:    @payload,
-          context:  @context.dup,
-          params:   @params,
-          streams:  agent_streams
-        ).call.result
-      end
+      streams = { token: @token_stream, agent: @agent_event_stream, tribunal: @tribunal_event_stream }.compact
+      step.agent_class.new(
+        input:   @payload,
+        context: @context.dup,
+        params:  @params,
+        streams: streams
+      ).call.result
     end
   end
 end

data/lib/active_harness/result.rb

@@ -4,8 +4,20 @@ module ActiveHarness
   # Minimal result wrapper returned by Agent#call.
   #
   # output — raw string from the provider
-  # parsed — for format :json: a Ruby Hash/Array; for format :text: same as output
+  # processed — for format :json: a Ruby Hash/Array; for format :text: same as output
   # usage  — token counts: { input_tokens:, output_tokens:, total_tokens: } or nil for streaming
   # cost   — { input_cost:, output_cost:, total_cost: } in USD, or nil if pricing unavailable
-  Result = Struct.new(:input, :output, :parsed, :system_prompt, :provider, :model, :temperature, :model_list, :attempts, :execution_time, :usage, :cost, keyword_init: true)
+  Result = Struct.new(
+    :input,
+    :output,
+    :processed,
+    :system_prompt, 
+    :provider, :model,
+    :temperature,
+    :model_list,
+    :attempts,
+    :execution_time,
+    :usage,
+    :cost,
+    keyword_init: true)
 end

data/lib/active_harness/tribunal/dsl.rb

@@ -13,7 +13,7 @@ module ActiveHarness
       # Receives the full results array; return value becomes #verdict.
       # Takes priority over +verdict+ strategy if both are declared.
       #
-      #   process { |results| results.all? { |r| r.parsed["result"] == true } }
+      #   process { |results| results.all? { |r| r.processed["result"] == true } }
       def process(&block)
         tribunal_config[:process] = block
       end
@@ -31,11 +31,11 @@ module ActiveHarness
       # The block receives a single Result and must return a truthy/falsy value.
       #
       #   verdict :unanimous do |result|
-      #     result.parsed["result"] == true
+      #     result.processed["result"] == true
       #   end
       #
       #   verdict :majority, may_fail: 1 do |result|
-      #     result.parsed["result"] == true
+      #     result.processed["result"] == true
       #   end
       VALID_STRATEGIES = %i[unanimous majority].freeze
 

data/lib/active_harness/tribunal/processing.rb

@@ -2,7 +2,7 @@ module ActiveHarness
   class Tribunal
     # Instance-level process block — overrides class-level block.
     #
-    #   tribunal.process { |results| results.count { |r| r.parsed["ok"] } >= 2 }
+    #   tribunal.process { |results| results.count { |r| r.processed["ok"] } >= 2 }
     def process(&block)
       @process_block = block
       self

data/lib/active_harness/tribunal.rb

@@ -17,14 +17,14 @@ module ActiveHarness
   #     timeout: 7
   #   )
   #   tribunal.on(:after_agent) { |result| puts result.model }
-  #   tribunal.process { |results| results.all? { |r| r.parsed["result"] == true } }
+  #   tribunal.process { |results| results.all? { |r| r.processed["result"] == true } }
   #   tribunal.call
   #
   # Subclass with DSL:
   #   class ContentQualityTribunal < ActiveHarness::Tribunal
   #     agents PolitenessAgent, ConstructivenessAgent
   #     on(:after_agent) { |result| puts result.model }
-  #     process { |results| results.all? { |r| r.parsed["result"] == true } }
+  #     process { |results| results.all? { |r| r.processed["result"] == true } }
   #   end
   #   ContentQualityTribunal.new(input: "...").call
   #
@@ -89,6 +89,17 @@ module ActiveHarness
       @agent_execution_times = []
     end
 
+    # Returns a Result with processed: { "verdict" => @verdict } so the pipeline
+    # can handle agents and tribunals through the same interface.
+    def result
+      Result.new(
+        input:          @input,
+        output:         nil,
+        processed:      { "verdict" => @verdict },
+        execution_time: @execution_time
+      )
+    end
+
     # Run all agents in parallel, then compute the verdict.
     # Returns self so calls can be chained: tribunal.call.verdict
     #

data/lib/active_harness.rb

@@ -30,7 +30,7 @@ require_relative "active_harness/pipeline"
 require_relative "active_harness/railtie" if defined?(Rails::Railtie)
 
 module ActiveHarness
-  VERSION = "0.2.24"
+  VERSION = "0.2.26"
 
   class << self
     # Configure ActiveHarness.

data/lib/generators/active_harness/install/templates/memory/app_memory.rb

@@ -1,16 +1,16 @@
-class AppMemory < ActiveHarness::Memory
-  # Usage: AppMemory.new(session_id: "user_42")
+class AppMemory < ActiveHarness::Memory::JsonFile
+  # Usage: AppMemory.new(file_name: "users/42")
   #
-  # Wraps ActiveHarness::Memory with project defaults so callers
-  # only need to pass a session_id.
-  def initialize(session_id:)
+  # Wraps ActiveHarness::Memory::JsonFile with project defaults so callers
+  # only need to pass a file_name. Slashes create subdirectories.
+  def initialize(file_name:, **opts)
     super(
-      session_id:   session_id,
+      file_name:    file_name,
+      storage_path: Rails.root.join("storage", "ai", "memory").to_s,
       depth:        10,
-      adapter:      :file,
-      path:         Rails.root.join("storage", "ai", "memory").to_s,
       storage_size: 200,
-      pretty:       Rails.env.development?
+      pretty:       Rails.env.development?,
+      **opts
     )
   end
 end

data/lib/generators/active_harness/install/templates/tribunals/support_guard_tribunal.rb

@@ -6,6 +6,6 @@ class SupportGuardTribunal < ActiveHarness::Tribunal
   agents SupportGuardAgent
 
   process do |results|
-    results.none? { |r| r.parsed["spam"] == true }
+    results.none? { |r| r.processed["spam"] == true }
   end
 end

data/lib/generators/active_harness/memory/templates/memory.rb.tt

@@ -1,12 +1,12 @@
-class <%= class_name %>Memory < ActiveHarness::Memory
-  def initialize(session_id:)
+class <%= class_name %>Memory < ActiveHarness::Memory::JsonFile
+  def initialize(file_name:, **opts)
     super(
-      session_id:   session_id,
+      file_name:    file_name,
+      storage_path: Rails.root.join("storage", "ai", "memory").to_s,
       depth:        10,
-      adapter:      :file,
-      path:         Rails.root.join("storage", "ai", "memory").to_s,
       storage_size: 200,
-      pretty:       Rails.env.development?
+      pretty:       Rails.env.development?,
+      **opts
     )
   end
 end

data/lib/generators/active_harness/memory_postgresql/memory_postgresql_generator.rb

@@ -0,0 +1,23 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveHarness
+  module Generators
+    class MemoryPostgresqlGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the ActiveHarness PostgreSQL memory migration"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "create_active_harness_memory_turns.rb.tt",
+                           "db/migrate/create_active_harness_memory_turns.rb"
+      end
+    end
+  end
+end

data/lib/generators/active_harness/memory_postgresql/templates/create_active_harness_memory_turns.rb.tt

@@ -0,0 +1,16 @@
+class CreateActiveHarnessMemoryTurns < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :active_harness_memory_turns do |t|
+      t.text     :session_id, null: false
+      t.text     :namespace
+      t.text     :request,    null: false
+      t.text     :response,   null: false
+      t.jsonb    :meta,       null: false, default: {}
+      t.datetime :created_at, null: false, default: -> { "NOW()" }
+    end
+
+    add_index :active_harness_memory_turns,
+              [:session_id, :namespace, :id],
+              name: "idx_ah_memory_turns_session"
+  end
+end

data/lib/generators/active_harness/memory_sqlite/memory_sqlite_generator.rb

@@ -0,0 +1,23 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveHarness
+  module Generators
+    class MemorySqliteGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the ActiveHarness SQLite memory migration"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "create_active_harness_memory_turns.rb.tt",
+                           "db/migrate/create_active_harness_memory_turns.rb"
+      end
+    end
+  end
+end

data/lib/generators/active_harness/memory_sqlite/templates/create_active_harness_memory_turns.rb.tt

@@ -0,0 +1,16 @@
+class CreateActiveHarnessMemoryTurns < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :active_harness_memory_turns do |t|
+      t.text     :session_id, null: false
+      t.text     :namespace
+      t.text     :request,    null: false
+      t.text     :response,   null: false
+      t.text     :meta,       null: false, default: "{}"
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :active_harness_memory_turns,
+              [:session_id, :namespace, :id],
+              name: "idx_ah_memory_turns_session"
+  end
+end

data/lib/generators/active_harness/tribunal/templates/tribunal.rb.tt

@@ -2,6 +2,6 @@ class <%= class_name %>Tribunal < ActiveHarness::Tribunal
   agents <%= class_name %>Agent
 
   process do |results|
-    results.all? { |r| r.parsed["result"] == true }
+    results.all? { |r| r.processed["result"] == true }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_harness
 version: !ruby/object:Gem::Version
-  version: 0.2.24
+  version: 0.2.26
 platform: ruby
 authors:
 - the-teacher
@@ -50,9 +50,11 @@ files:
 - lib/active_harness/http/streaming_client.rb
 - lib/active_harness/memory.rb
 - lib/active_harness/memory/adapter/base.rb
-- lib/active_harness/memory/adapter/file.rb
-- lib/active_harness/memory/json_file.rb
+- lib/active_harness/memory/adapter/json_file.rb
+- lib/active_harness/memory/adapter/postgresql.rb
+- lib/active_harness/memory/adapter/sqlite.rb
 - lib/active_harness/pipeline.rb
+- lib/active_harness/pipeline/README.md
 - lib/active_harness/pipeline/hooks.rb
 - lib/active_harness/pipeline/step.rb
 - lib/active_harness/providers/PROVIDER_CONTRACT.md
@@ -92,6 +94,10 @@ files:
 - lib/generators/active_harness/install/templates/tribunals/support_guard_tribunal.rb
 - lib/generators/active_harness/memory/memory_generator.rb
 - lib/generators/active_harness/memory/templates/memory.rb.tt
+- lib/generators/active_harness/memory_postgresql/memory_postgresql_generator.rb
+- lib/generators/active_harness/memory_postgresql/templates/create_active_harness_memory_turns.rb.tt
+- lib/generators/active_harness/memory_sqlite/memory_sqlite_generator.rb
+- lib/generators/active_harness/memory_sqlite/templates/create_active_harness_memory_turns.rb.tt
 - lib/generators/active_harness/pipeline/pipeline_generator.rb
 - lib/generators/active_harness/pipeline/templates/pipeline.rb.tt
 - lib/generators/active_harness/prompt/prompt_generator.rb

data/lib/active_harness/memory/json_file.rb

@@ -1,44 +0,0 @@
-module ActiveHarness
-  class Memory
-    # File-backed memory with a path-safe file_name interface.
-    #
-    # Differences from the base Memory class:
-    #   - file_name:    replaces session_id — may contain slashes to create
-    #                   subdirectories under storage_path, e.g. "users/42/chat"
-    #                   Final file is always <storage_path>/<file_name>.json
-    #   - storage_path: replaces the adapter-level path: option
-    #   - adapter:      always :file — no other adapter can be passed
-    #
-    # Path traversal is rejected: segments equal to "." or ".." or containing
-    # null bytes raise ArgumentError before any file I/O happens.
-    # Missing directories are created automatically on the first write.
-    class JsonFile < Memory
-      DEFAULT_STORAGE_PATH = "storage/ai/memory"
-
-      def initialize(file_name:, storage_path: DEFAULT_STORAGE_PATH, **opts)
-        super(
-          session_id:   sanitize!(file_name),
-          adapter:      :file,
-          path:         storage_path,
-          **opts
-        )
-      end
-
-      private
-
-      def sanitize!(raw)
-        parts = raw.to_s.split("/").map(&:strip).reject(&:empty?)
-        raise ArgumentError, "file_name must not be empty" if parts.empty?
-
-        parts.each do |part|
-          if part == ".." || part == "." || part.include?("\0")
-            raise ArgumentError, "Invalid file_name segment: #{part.inspect}"
-          end
-        end
-
-        parts.last.sub!(/\.json\z/i, "")
-        parts.join("/")
-      end
-    end
-  end
-end