spurline-docs 0.3.0

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

data/lib/spurline/spur.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Spurline
+  # Base class for spur gems. Spur gems are standard Ruby gems that self-register
+  # tools and permissions into the Spurline framework on require.
+  #
+  # The spur contract is locked — this interface cannot change after ship.
+  #
+  # Usage in a spur gem (e.g., spurline-web):
+  #
+  #   module SpurlineWeb
+  #     class Railtie < Spurline::Spur
+  #       spur_name "spurline-web"
+  #
+  #       tools do
+  #         register :web_search, SpurlineWeb::Tools::WebSearch
+  #         register :scrape,     SpurlineWeb::Tools::Scraper
+  #       end
+  #
+  #       permissions do
+  #         default_trust :external
+  #         requires_confirmation false
+  #       end
+  #     end
+  #   end
+  #
+  class Spur
+    class << self
+      # Track all registered spurs for introspection.
+      def registry
+        @registry ||= {}
+      end
+
+      # Tool registrations deferred because Agent wasn't loaded yet.
+      def pending_registrations
+        @pending_registrations ||= []
+      end
+
+      # Adapter registrations deferred because Agent wasn't loaded yet.
+      def pending_adapter_registrations
+        @pending_adapter_registrations ||= []
+      end
+
+      # Replay deferred tool registrations into the given tool registry.
+      def flush_pending_registrations!(registry)
+        return if pending_registrations.empty?
+
+        pending_registrations.each do |registration|
+          registry.register(registration[:name], registration[:tool_class])
+        end
+        pending_registrations.clear
+      end
+
+      # Replay deferred adapter registrations into the given adapter registry.
+      def flush_pending_adapter_registrations!(registry)
+        return if pending_adapter_registrations.empty?
+
+        pending_adapter_registrations.each do |registration|
+          registry.register(registration[:name], registration[:adapter_class])
+        end
+        pending_adapter_registrations.clear
+      end
+
+      # Called by subclasses to set the spur gem name.
+      def spur_name(name = nil)
+        if name
+          @spur_name = name
+        else
+          @spur_name || self.name
+        end
+      end
+
+      # DSL block for registering tools.
+      def tools(&block)
+        @tool_registrations ||= []
+        if block
+          context = ToolRegistrationContext.new
+          context.instance_eval(&block)
+          @tool_registrations = context.registrations
+        end
+        @tool_registrations
+      end
+
+      # DSL block for registering adapters.
+      def adapters(&block)
+        @adapter_registrations ||= []
+        if block
+          context = AdapterRegistrationContext.new
+          context.instance_eval(&block)
+          @adapter_registrations = context.registrations
+        end
+        @adapter_registrations
+      end
+
+      # DSL block for declaring default permissions.
+      def permissions(&block)
+        @permission_defaults ||= {}
+        if block
+          context = PermissionContext.new
+          context.instance_eval(&block)
+          @permission_defaults = context.settings
+        end
+        @permission_defaults
+      end
+
+      # Hook called when a subclass is defined. Auto-registers the spur.
+      def inherited(subclass)
+        super
+        # Defer registration to allow the class body to execute first.
+        TracePoint.new(:end) do |tp|
+          if tp.self == subclass
+            tp.disable
+            subclass.send(:auto_register!)
+          end
+        end.enable
+      end
+
+      private
+
+      # Auto-registers this spur's tools and adapters into the global
+      # Spurline::Agent registries. If Agent hasn't been loaded yet (Zeitwerk
+      # lazy loading), the registrations are deferred and replayed when the
+      # respective registry is first accessed.
+      def auto_register!
+        Spur.registry[spur_name] = {
+          tools: tools.map { |r| r[:name] },
+          adapters: adapters.map { |r| r[:name] },
+          permissions: permissions,
+        }
+
+        register_tools!
+        register_adapters!
+      end
+
+      def register_tools!
+        return if tools.empty?
+
+        if defined?(Spurline::Agent) && Spurline::Agent.respond_to?(:tool_registry)
+          tools.each do |registration|
+            Spurline::Agent.tool_registry.register(
+              registration[:name],
+              registration[:tool_class]
+            )
+          end
+        else
+          Spur.pending_registrations.concat(tools)
+        end
+      end
+
+      def register_adapters!
+        return if adapters.empty?
+
+        if defined?(Spurline::Agent) && Spurline::Agent.respond_to?(:adapter_registry)
+          adapters.each do |registration|
+            Spurline::Agent.adapter_registry.register(
+              registration[:name],
+              registration[:adapter_class]
+            )
+          end
+        else
+          Spur.pending_adapter_registrations.concat(adapters)
+        end
+      end
+    end
+
+    # Context object for the `tools` DSL block.
+    class ToolRegistrationContext
+      attr_reader :registrations
+
+      def initialize
+        @registrations = []
+      end
+
+      def register(name, tool_class)
+        @registrations << { name: name.to_sym, tool_class: tool_class }
+      end
+    end
+
+    # Context object for the `adapters` DSL block.
+    class AdapterRegistrationContext
+      attr_reader :registrations
+
+      def initialize
+        @registrations = []
+      end
+
+      def register(name, adapter_class)
+        @registrations << { name: name.to_sym, adapter_class: adapter_class }
+      end
+    end
+
+    # Context object for the `permissions` DSL block.
+    class PermissionContext
+      attr_reader :settings
+
+      def initialize
+        @settings = {}
+      end
+
+      def default_trust(level)
+        @settings[:default_trust] = level
+      end
+
+      def requires_confirmation(val = true)
+        @settings[:requires_confirmation] = val
+      end
+
+      def sandbox(val = true)
+        @settings[:sandbox] = val
+      end
+    end
+  end
+end