spurline-core 0.3.0

data/lib/spurline/session/session.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Spurline
+  module Session
+    # The running record of an agent conversation. Framework-owned (ADR-004).
+    # Sessions are created via .load_or_create — never call .new directly in agent code.
+    #
+    # State transitions are enforced via Lifecycle::States.
+    class Session
+      attr_reader :id, :agent_class, :user, :turns, :state,
+                  :started_at, :finished_at, :metadata
+
+      def initialize(id:, store:, agent_class: nil, user: nil)
+        @id = id
+        @store = store
+        @agent_class = agent_class
+        @user = user
+        @turns = []
+        @state = :ready
+        @started_at = Time.now
+        @finished_at = nil
+        @metadata = {}
+      end
+
+      # The only way to get a session. Loads an existing session by ID,
+      # or creates a new one if it doesn't exist.
+      def self.load_or_create(id: nil, store:, **opts)
+        id ||= SecureRandom.uuid
+
+        if store.exists?(id)
+          store.load(id)
+        else
+          session = new(id: id, store: store, **opts)
+          store.save(session)
+          session
+        end
+      end
+
+      # Rebuilds a session from persisted attributes without running initialize.
+      def self.restore(data, store:)
+        session = allocate
+        session.instance_variable_set(:@id, data[:id])
+        session.instance_variable_set(:@store, store)
+        session.instance_variable_set(:@agent_class, data[:agent_class])
+        session.instance_variable_set(:@user, data[:user])
+        session.instance_variable_set(:@turns, data[:turns])
+        session.instance_variable_set(:@state, data[:state])
+        session.instance_variable_set(:@started_at, data[:started_at])
+        session.instance_variable_set(:@finished_at, data[:finished_at])
+        session.instance_variable_set(:@metadata, data[:metadata] || {})
+        session
+      end
+
+      def start_turn(input:)
+        turn = Turn.new(input: input, number: turns.length + 1)
+        @turns << turn
+        @metadata[:last_turn_started_at] = turn.started_at
+        turn
+      end
+
+      def current_turn
+        @turns.last
+      end
+
+      def finish_turn!(output:)
+        current_turn&.finish!(output: output)
+        save!
+      end
+
+      def tool_calls
+        turns.flat_map(&:tool_calls)
+      end
+
+      def tool_call_count
+        tool_calls.length
+      end
+
+      def turn_count
+        turns.length
+      end
+
+      # Enforces valid state transitions via Lifecycle::States.
+      def transition_to!(new_state)
+        Lifecycle::States.validate_transition!(@state, new_state)
+        @state = new_state
+      end
+
+      def complete!
+        @state = :complete
+        @finished_at = Time.now
+        @metadata[:total_turns] = turn_count
+        @metadata[:total_tool_calls] = tool_call_count
+        @metadata[:total_duration_ms] = total_duration_ms
+        save!
+      end
+
+      def error!(error = nil)
+        @state = :error
+        @finished_at = Time.now
+        @metadata[:last_error] = error&.message
+        @metadata[:last_error_class] = error&.class&.name
+        save!
+      end
+
+      # Suspends the session and persists a checkpoint for later resumption.
+      def suspend!(checkpoint:)
+        Suspension.suspend!(self, checkpoint: checkpoint)
+      end
+
+      # Resumes a suspended session and clears the persisted checkpoint.
+      def resume!
+        Suspension.resume!(self)
+      end
+
+      # Whether the session is currently suspended.
+      def suspended?
+        Suspension.suspended?(self)
+      end
+
+      # Duration in seconds (float).
+      def duration
+        return nil unless finished_at
+
+        finished_at - started_at
+      end
+
+      # Duration in milliseconds (integer).
+      def total_duration_ms
+        return nil unless finished_at
+
+        ((finished_at - started_at) * 1000).round
+      end
+
+      # Compact summary for logging and debugging.
+      def summary
+        {
+          id: id,
+          state: state,
+          turns: turn_count,
+          tool_calls: tool_call_count,
+          duration_ms: total_duration_ms,
+        }
+      end
+
+      private
+
+      def save!
+        @store.save(self)
+      end
+    end
+  end
+end

data/lib/spurline/session/store/CLAUDE.md

@@ -0,0 +1,12 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3782 | 10:23 PM | 🔵 | Spurline session and state machine architecture analyzed for suspended sessions feature | ~700 |
+| #3661 | 7:57 PM | 🔵 | Code quality review confirmed Plans 01-02 are production-ready with zero issues | ~791 |
+</claude-mem-context>

data/lib/spurline/session/store/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Session
+    module Store
+      # Abstract interface for session storage adapters (ADR-004).
+      # The framework owns session persistence — developers do not manage it.
+      class Base
+        def save(session)
+          raise NotImplementedError, "#{self.class.name} must implement #save"
+        end
+
+        def load(id)
+          raise NotImplementedError, "#{self.class.name} must implement #load"
+        end
+
+        def delete(id)
+          raise NotImplementedError, "#{self.class.name} must implement #delete"
+        end
+
+        def exists?(id)
+          raise NotImplementedError, "#{self.class.name} must implement #exists?"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/session/store/memory.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Session
+    module Store
+      # In-memory session store. Suitable for development and testing.
+      # Data does not persist across process restarts.
+      # Thread-safe via Mutex for concurrent access.
+      class Memory < Base
+        def initialize
+          @store = {}
+          @mutex = Mutex.new
+        end
+
+        def save(session)
+          @mutex.synchronize { @store[session.id] = session }
+        end
+
+        def load(id)
+          @mutex.synchronize { @store[id] }
+        end
+
+        def delete(id)
+          @mutex.synchronize { @store.delete(id) }
+        end
+
+        def exists?(id)
+          @mutex.synchronize { @store.key?(id) }
+        end
+
+        def size
+          @mutex.synchronize { @store.size }
+        end
+
+        def clear!
+          @mutex.synchronize { @store.clear }
+        end
+
+        def ids
+          @mutex.synchronize { @store.keys.dup }
+        end
+      end
+    end
+  end
+end

data/lib/spurline/session/store/postgres.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Spurline
+  module Session
+    module Store
+      # PostgreSQL-backed session store. Persists sessions across process restarts.
+      # Thread-safe via a single connection guarded by a Mutex.
+      class Postgres < Base
+        TABLE_NAME = "spurline_sessions"
+
+        def initialize(url: Spurline.config.session_store_postgres_url, serializer: Spurline::Session::Serializer.new)
+          @url = url
+          @serializer = serializer
+          @mutex = Mutex.new
+          @connection = nil
+          require_pg!
+          ensure_url!
+        end
+
+        def save(session)
+          now = Time.now.utc.iso8601(6)
+          payload = @serializer.to_json(session)
+
+          @mutex.synchronize do
+            connection.exec_params(
+              <<~SQL,
+                INSERT INTO #{TABLE_NAME} (id, state, agent_class, created_at, updated_at, data)
+                VALUES ($1, $2, $3, COALESCE((SELECT created_at FROM #{TABLE_NAME} WHERE id = $1), $4), $5, $6::jsonb)
+                ON CONFLICT (id) DO UPDATE SET
+                  state = EXCLUDED.state,
+                  agent_class = EXCLUDED.agent_class,
+                  updated_at = EXCLUDED.updated_at,
+                  data = EXCLUDED.data
+              SQL
+              [session.id, session.state.to_s, session.agent_class, now, now, payload]
+            )
+          end
+
+          session
+        end
+
+        # ASYNC-READY: Keep read path isolated for future async driver swap.
+        def load(id)
+          row = @mutex.synchronize do
+            result = connection.exec_params(
+              "SELECT data::text AS data FROM #{TABLE_NAME} WHERE id = $1 LIMIT 1",
+              [id]
+            )
+            result.ntuples.positive? ? result[0] : nil
+          end
+          return nil unless row
+
+          payload = row.fetch("data")
+          @serializer.from_json(payload, store: self)
+        end
+
+        def delete(id)
+          @mutex.synchronize do
+            connection.exec_params("DELETE FROM #{TABLE_NAME} WHERE id = $1", [id])
+          end
+        end
+
+        def exists?(id)
+          @mutex.synchronize do
+            result = connection.exec_params("SELECT 1 FROM #{TABLE_NAME} WHERE id = $1 LIMIT 1", [id])
+            result.ntuples.positive?
+          end
+        end
+
+        def size
+          @mutex.synchronize do
+            connection.exec("SELECT COUNT(*) FROM #{TABLE_NAME}")[0]["count"].to_i
+          end
+        end
+
+        def clear!
+          @mutex.synchronize do
+            connection.exec("DELETE FROM #{TABLE_NAME}")
+          end
+        end
+
+        def ids
+          @mutex.synchronize do
+            connection.exec("SELECT id FROM #{TABLE_NAME} ORDER BY id").map { |row| row.fetch("id") }
+          end
+        end
+
+        def close
+          @mutex.synchronize do
+            @connection&.close
+            @connection = nil
+          end
+        end
+
+        private
+
+        def ensure_url!
+          return if @url && !@url.strip.empty?
+
+          raise Spurline::ConfigurationError,
+            "session_store_postgres_url must be set when using :postgres session store."
+        end
+
+        def require_pg!
+          return if defined?(::PG::Connection)
+
+          require "pg"
+        rescue LoadError
+          raise Spurline::PostgresUnavailableError,
+            "The 'pg' gem is required for the :postgres session store. Add gem \"pg\" to your Gemfile."
+        end
+
+        # ASYNC-READY: This connection boundary is where pooling/non-blocking
+        # clients can be introduced without changing the store contract.
+        def connection
+          @connection ||= PG.connect(@url)
+        end
+      end
+    end
+  end
+end

data/lib/spurline/session/store/sqlite.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+
+module Spurline
+  module Session
+    module Store
+      # SQLite-backed session store. Persists sessions across process restarts.
+      # Thread-safe via a single connection guarded by a Mutex.
+      class SQLite < Base
+        TABLE_NAME = "spurline_sessions"
+
+        def initialize(path: Spurline.config.session_store_path, serializer: Spurline::Session::Serializer.new)
+          @path = path
+          @serializer = serializer
+          @mutex = Mutex.new
+          @db = nil
+        end
+
+        def save(session)
+          now = Time.now.utc.iso8601(6)
+          payload = @serializer.to_json(session)
+
+          @mutex.synchronize do
+            db.execute(
+              <<~SQL,
+                INSERT OR REPLACE INTO #{TABLE_NAME}
+                (id, state, agent_class, created_at, updated_at, data)
+                VALUES (
+                  ?,
+                  ?,
+                  ?,
+                  COALESCE((SELECT created_at FROM #{TABLE_NAME} WHERE id = ?), ?),
+                  ?,
+                  ?
+                )
+              SQL
+              [session.id, session.state.to_s, session.agent_class, session.id, now, now, payload]
+            )
+          end
+
+          session
+        end
+
+        def load(id)
+          row = @mutex.synchronize do
+            db.get_first_row("SELECT data FROM #{TABLE_NAME} WHERE id = ? LIMIT 1", [id])
+          end
+          return nil unless row
+
+          payload = row.fetch("data")
+          @serializer.from_json(payload, store: self)
+        end
+
+        def delete(id)
+          @mutex.synchronize do
+            db.execute("DELETE FROM #{TABLE_NAME} WHERE id = ?", [id])
+          end
+        end
+
+        def exists?(id)
+          @mutex.synchronize do
+            !db.get_first_value("SELECT 1 FROM #{TABLE_NAME} WHERE id = ? LIMIT 1", [id]).nil?
+          end
+        end
+
+        def size
+          @mutex.synchronize do
+            db.get_first_value("SELECT COUNT(*) FROM #{TABLE_NAME}").to_i
+          end
+        end
+
+        def clear!
+          @mutex.synchronize do
+            db.execute("DELETE FROM #{TABLE_NAME}")
+          end
+        end
+
+        def ids
+          @mutex.synchronize do
+            db.execute("SELECT id FROM #{TABLE_NAME} ORDER BY id").map { |row| row.fetch("id") }
+          end
+        end
+
+        private
+
+        # ASYNC-READY: This connection boundary is where async adapters can
+        # introduce pooled or non-blocking persistence later.
+        def db
+          @db ||= begin
+            require_sqlite3!
+            ensure_parent_directory!
+            connection = ::SQLite3::Database.new(@path)
+            connection.results_as_hash = true
+            connection.busy_timeout(5_000)
+            connection.execute("PRAGMA journal_mode = WAL")
+            connection.execute("PRAGMA synchronous = NORMAL")
+            connection.execute(
+              <<~SQL
+                CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+                  id TEXT PRIMARY KEY,
+                  state TEXT NOT NULL,
+                  agent_class TEXT,
+                  created_at TEXT NOT NULL,
+                  updated_at TEXT NOT NULL,
+                  data TEXT NOT NULL
+                )
+              SQL
+            )
+            connection.execute("CREATE INDEX IF NOT EXISTS idx_spurline_sessions_state ON #{TABLE_NAME}(state)")
+            connection.execute(
+              "CREATE INDEX IF NOT EXISTS idx_spurline_sessions_agent_class ON #{TABLE_NAME}(agent_class)"
+            )
+            connection
+          end
+        end
+
+        def require_sqlite3!
+          return if defined?(::SQLite3::Database)
+
+          require "sqlite3"
+        rescue LoadError
+          raise Spurline::SQLiteUnavailableError,
+            "sqlite3 gem is required for the :sqlite session store. Add gem \"sqlite3\" to your Gemfile."
+        end
+
+        def ensure_parent_directory!
+          return if @path == ":memory:"
+
+          parent = File.dirname(@path)
+          return if parent.nil? || parent == "." || parent.empty?
+
+          FileUtils.mkdir_p(parent)
+        end
+      end
+    end
+  end
+end

data/lib/spurline/session/suspension.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Spurline
+  module Session
+    # Suspension logic for sessions.
+    # Kept as a standalone module so Session internals remain unchanged.
+    module Suspension
+      SUSPENSION_KEY = :suspension_checkpoint
+      SUSPENDABLE_STATES = %i[running waiting_for_tool processing].freeze
+
+      # Suspends a session, saving a checkpoint for later resumption.
+      def self.suspend!(session, checkpoint:)
+        raise Spurline::SuspensionError, "Session is already suspended" if suspended?(session)
+
+        unless suspendable?(session)
+          raise Spurline::SuspensionError,
+            "Session cannot be suspended from state #{session.state.inspect}"
+        end
+
+        session.metadata[SUSPENSION_KEY] = normalize_checkpoint(session, checkpoint)
+        session.transition_to!(:suspended)
+        persist!(session)
+        session
+      end
+
+      # Resumes a suspended session, clearing the checkpoint.
+      def self.resume!(session)
+        unless suspended?(session)
+          raise Spurline::InvalidResumeError,
+            "Session is not suspended (state=#{session.state.inspect})"
+        end
+
+        session.metadata[SUSPENSION_KEY] = nil
+        session.transition_to!(:running)
+        persist!(session)
+        session
+      end
+
+      # Returns true if session is in :suspended state.
+      def self.suspended?(session)
+        session.state == :suspended
+      end
+
+      # Returns the checkpoint hash, or nil if not suspended.
+      def self.checkpoint_for(session)
+        return nil unless suspended?(session)
+
+        session.metadata[SUSPENSION_KEY]
+      end
+
+      # Validates that a session can be suspended from its current state.
+      def self.suspendable?(session)
+        SUSPENDABLE_STATES.include?(session.state)
+      end
+
+      def self.normalize_checkpoint(session, checkpoint)
+        unless checkpoint.is_a?(Hash)
+          raise ArgumentError, "checkpoint must be a Hash"
+        end
+
+        {
+          loop_iteration: fetch(checkpoint, :loop_iteration) || 0,
+          last_tool_result: fetch(checkpoint, :last_tool_result),
+          messages_so_far: Array(fetch(checkpoint, :messages_so_far)),
+          turn_number: fetch(checkpoint, :turn_number) || infer_turn_number(session),
+          suspended_at: fetch(checkpoint, :suspended_at) || Time.now.utc.iso8601,
+          suspension_reason: fetch(checkpoint, :suspension_reason),
+        }
+      end
+      private_class_method :normalize_checkpoint
+
+      def self.fetch(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+      private_class_method :fetch
+
+      def self.infer_turn_number(session)
+        return session.current_turn.number if session.respond_to?(:current_turn) && session.current_turn
+        return session.turn_count if session.respond_to?(:turn_count)
+
+        0
+      end
+      private_class_method :infer_turn_number
+
+      def self.persist!(session)
+        session.send(:save!)
+      end
+      private_class_method :persist!
+    end
+  end
+end

data/lib/spurline/session/turn.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Session
+    # A single turn in a conversation. Holds the input, output, tool calls,
+    # and timing information. Turns are mutable during their lifecycle and
+    # become effectively immutable once finished.
+    class Turn
+      attr_reader :input, :output, :tool_calls, :started_at, :finished_at,
+                  :number, :metadata
+
+      def initialize(input:, number:)
+        @input = input
+        @output = nil
+        @tool_calls = []
+        @number = number
+        @started_at = Time.now
+        @finished_at = nil
+        @metadata = {}
+      end
+
+      # Rebuilds a turn from persisted attributes without running initialize.
+      def self.restore(data)
+        turn = allocate
+        turn.instance_variable_set(:@input, data[:input])
+        turn.instance_variable_set(:@output, data[:output])
+        turn.instance_variable_set(:@tool_calls, data[:tool_calls] || [])
+        turn.instance_variable_set(:@number, data[:number])
+        turn.instance_variable_set(:@started_at, data[:started_at])
+        turn.instance_variable_set(:@finished_at, data[:finished_at])
+        turn.instance_variable_set(:@metadata, data[:metadata] || {})
+        turn
+      end
+
+      def finish!(output:)
+        @output = output
+        @finished_at = Time.now
+        @metadata[:duration_ms] = duration_ms
+      end
+
+      def record_tool_call(
+        name:,
+        arguments:,
+        result:,
+        duration_ms:,
+        scope_id: nil,
+        idempotency_key: nil,
+        was_cached: nil,
+        cache_age_ms: nil
+      )
+        entry = {
+          name: name,
+          arguments: arguments,
+          result: result,
+          duration_ms: duration_ms,
+          timestamp: Time.now,
+        }
+        entry[:scope_id] = scope_id unless scope_id.nil?
+        entry[:idempotency_key] = idempotency_key unless idempotency_key.nil?
+        entry[:was_cached] = was_cached unless was_cached.nil?
+        entry[:cache_age_ms] = cache_age_ms unless cache_age_ms.nil?
+        @tool_calls << entry
+      end
+
+      # Duration in seconds (float).
+      def duration
+        return nil unless finished_at
+
+        finished_at - started_at
+      end
+
+      # Duration in milliseconds (integer), for audit logging.
+      def duration_ms
+        return nil unless finished_at
+
+        ((finished_at - started_at) * 1000).round
+      end
+
+      def tool_call_count
+        tool_calls.length
+      end
+
+      def complete?
+        !finished_at.nil?
+      end
+
+      # Compact summary for logging and debugging.
+      def summary
+        {
+          number: number,
+          tool_calls: tool_call_count,
+          duration_ms: duration_ms,
+          complete: complete?,
+        }
+      end
+    end
+  end
+end