rubyn-code 0.1.0

data/lib/rubyn_code/memory/session_persistence.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module RubynCode
+  module Memory
+    # Saves and restores full conversation sessions to SQLite, enabling
+    # session continuity across process restarts and session browsing.
+    class SessionPersistence
+      # @param db [DB::Connection] database connection
+      def initialize(db)
+        @db = db
+        ensure_table
+      end
+
+      # Persists a complete session snapshot.
+      #
+      # @param session_id [String] unique session identifier
+      # @param project_path [String] project this session belongs to
+      # @param messages [Array<Hash>] the conversation messages
+      # @param title [String, nil] human-readable session title
+      # @param model [String, nil] LLM model used
+      # @param metadata [Hash] arbitrary metadata
+      # @return [void]
+      def save_session(session_id:, project_path:, messages:, title: nil, model: nil, metadata: {})
+        now = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+        messages_json = JSON.generate(messages)
+        meta_json = JSON.generate(metadata)
+
+        @db.execute(<<~SQL, [session_id, project_path, title, model, messages_json, "active", meta_json, now, now, messages_json, title, model, meta_json, now])
+          INSERT INTO sessions (id, project_path, title, model, messages, status, metadata, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET
+            messages = ?,
+            title = COALESCE(?, title),
+            model = COALESCE(?, model),
+            metadata = ?,
+            updated_at = ?
+        SQL
+      end
+
+      # Loads a session by ID.
+      #
+      # @param session_id [String]
+      # @return [Hash, nil] { messages:, metadata:, title:, model:, status:, project_path: } or nil
+      def load_session(session_id)
+        rows = @db.query(
+          "SELECT * FROM sessions WHERE id = ?",
+          [session_id]
+        ).to_a
+        return nil if rows.empty?
+
+        row = rows.first
+        {
+          messages: parse_json_array(row["messages"]),
+          metadata: parse_json_hash(row["metadata"]),
+          title: row["title"],
+          model: row["model"],
+          status: row["status"],
+          project_path: row["project_path"],
+          created_at: row["created_at"],
+          updated_at: row["updated_at"]
+        }
+      end
+
+      # Lists sessions, optionally filtered by project and/or status.
+      #
+      # @param project_path [String, nil] filter by project
+      # @param status [String, nil] filter by status ("active", "archived", "deleted")
+      # @param limit [Integer] maximum results (default 20)
+      # @return [Array<Hash>] session summaries (without full messages)
+      def list_sessions(project_path: nil, status: nil, limit: 20)
+        conditions = []
+        params = []
+
+        if project_path
+          conditions << "project_path = ?"
+          params << project_path
+        end
+
+        if status
+          conditions << "status = ?"
+          params << status
+        end
+
+        where_clause = conditions.empty? ? "" : "WHERE #{conditions.join(' AND ')}"
+        params << limit
+
+        rows = @db.query(<<~SQL, params).to_a
+          SELECT id, project_path, title, model, status, metadata, created_at, updated_at
+          FROM sessions
+          #{where_clause}
+          ORDER BY updated_at DESC
+          LIMIT ?
+        SQL
+
+        rows.map do |row|
+          {
+            id: row["id"],
+            project_path: row["project_path"],
+            title: row["title"],
+            model: row["model"],
+            status: row["status"],
+            metadata: parse_json_hash(row["metadata"]),
+            created_at: row["created_at"],
+            updated_at: row["updated_at"]
+          }
+        end
+      end
+
+      # Updates session attributes.
+      #
+      # @param session_id [String]
+      # @param attrs [Hash] attributes to update (:title, :status, :model, :metadata, :messages)
+      # @return [void]
+      def update_session(session_id, **attrs)
+        return if attrs.empty?
+
+        sets = []
+        params = []
+
+        attrs.each do |key, value|
+          case key
+          when :title
+            sets << "title = ?"
+            params << value
+          when :status
+            sets << "status = ?"
+            params << value
+          when :model
+            sets << "model = ?"
+            params << value
+          when :metadata
+            sets << "metadata = ?"
+            params << JSON.generate(value)
+          when :messages
+            sets << "messages = ?"
+            params << JSON.generate(value)
+          end
+        end
+
+        return if sets.empty?
+
+        sets << "updated_at = ?"
+        params << Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+        params << session_id
+
+        @db.execute("UPDATE sessions SET #{sets.join(', ')} WHERE id = ?", params)
+      end
+
+      # Deletes a session permanently.
+      #
+      # @param session_id [String]
+      # @return [void]
+      def delete_session(session_id)
+        @db.execute("DELETE FROM sessions WHERE id = ?", [session_id])
+      end
+
+      private
+
+      def ensure_table
+        # Add messages column if it doesn't exist (migration schema didn't include it)
+        @db.execute("ALTER TABLE sessions ADD COLUMN messages TEXT NOT NULL DEFAULT '[]'")
+      rescue StandardError
+        # Column already exists or table doesn't exist yet — either way, safe to continue
+      end
+
+      # @param raw [String, Array, nil]
+      # @return [Array]
+      def parse_json_array(raw)
+        case raw
+        when Array then raw
+        when String then JSON.parse(raw, symbolize_names: true)
+        else []
+        end
+      rescue JSON::ParserError
+        []
+      end
+
+      # @param raw [String, Hash, nil]
+      # @return [Hash]
+      def parse_json_hash(raw)
+        case raw
+        when Hash then raw
+        when String then JSON.parse(raw, symbolize_names: true)
+        else {}
+        end
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/rubyn_code/memory/store.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+require_relative "models"
+
+module RubynCode
+  module Memory
+    # Writes and manages memories in SQLite, backed by an FTS5 full-text
+    # search index for fast retrieval. Handles expiration and relevance
+    # decay to keep the memory store manageable over time.
+    class Store
+      # @param db [DB::Connection] database connection
+      # @param project_path [String] scoping path for this memory store
+      def initialize(db, project_path:)
+        @db = db
+        @project_path = project_path
+        ensure_tables
+      end
+
+      # Persists a new memory and updates the FTS index.
+      #
+      # @param content [String] the memory content
+      # @param tier [String] retention tier ("short", "medium", "long")
+      # @param category [String, nil] classification category
+      # @param metadata [Hash] arbitrary metadata
+      # @param expires_at [String, nil] ISO 8601 expiration timestamp
+      # @return [MemoryRecord] the created record
+      def write(content:, tier: "medium", category: nil, metadata: {}, expires_at: nil)
+        validate_tier!(tier)
+        validate_category!(category) if category
+
+        id = SecureRandom.uuid
+        now = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+        meta_json = JSON.generate(metadata)
+
+        @db.execute(<<~SQL, [id, @project_path, tier, category, content, 1.0, 0, now, expires_at, meta_json, now])
+          INSERT INTO memories (id, project_path, tier, category, content,
+                                relevance_score, access_count, last_accessed_at,
+                                expires_at, metadata, created_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        SQL
+
+        MemoryRecord.new(
+          id: id, project_path: @project_path, tier: tier, category: category,
+          content: content, relevance_score: 1.0, access_count: 0,
+          last_accessed_at: now, expires_at: expires_at, metadata: metadata,
+          created_at: now
+        )
+      end
+
+      # Updates attributes on an existing memory.
+      #
+      # @param id [String] the memory ID
+      # @param attrs [Hash] attributes to update (content, tier, category, metadata, expires_at, relevance_score)
+      # @return [void]
+      def update(id, **attrs)
+        return if attrs.empty?
+
+        sets = []
+        params = []
+
+        attrs.each do |key, value|
+          case key
+          when :content
+            sets << "content = ?"
+            params << value
+          when :tier
+            validate_tier!(value)
+            sets << "tier = ?"
+            params << value
+          when :category
+            validate_category!(value) if value
+            sets << "category = ?"
+            params << value
+          when :metadata
+            sets << "metadata = ?"
+            params << JSON.generate(value)
+          when :expires_at
+            sets << "expires_at = ?"
+            params << value
+          when :relevance_score
+            sets << "relevance_score = ?"
+            params << value.to_f
+          end
+        end
+
+        return if sets.empty?
+
+        params << id
+        @db.execute(
+          "UPDATE memories SET #{sets.join(', ')} WHERE id = ? AND project_path = '#{@project_path}'",
+          params
+        )
+
+        # Content changes are picked up by LIKE-based search — no FTS sync needed
+      end
+
+      # Deletes a memory and its FTS index entry.
+      #
+      # @param id [String]
+      # @return [void]
+      def delete(id)
+        @db.execute("DELETE FROM memories WHERE id = ? AND project_path = ?", [id, @project_path])
+      end
+
+      # Removes all memories whose expires_at is in the past.
+      #
+      # @return [Integer] number of expired memories deleted
+      def expire_old!
+        now = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+
+        expired_ids = @db.query(
+          "SELECT id FROM memories WHERE project_path = ? AND expires_at IS NOT NULL AND expires_at < ?",
+          [@project_path, now]
+        ).to_a.map { |row| row["id"] }
+
+        return 0 if expired_ids.empty?
+
+        placeholders = (["?"] * expired_ids.size).join(", ")
+        @db.execute(
+          "DELETE FROM memories WHERE id IN (#{placeholders}) AND project_path = ?",
+          expired_ids + [@project_path]
+        )
+
+        expired_ids.size
+      end
+
+      # Reduces the relevance_score of memories that have not been accessed
+      # recently, simulating natural memory decay.
+      #
+      # @param decay_rate [Float] amount to subtract from relevance_score (default 0.01)
+      # @return [void]
+      def decay!(decay_rate: 0.01)
+        cutoff = (Time.now.utc - 86_400).strftime("%Y-%m-%d %H:%M:%S") # 24 hours ago
+
+        @db.execute(<<~SQL, [decay_rate, @project_path, cutoff])
+          UPDATE memories
+          SET relevance_score = MAX(0.0, relevance_score - ?)
+          WHERE project_path = ?
+            AND last_accessed_at < ?
+        SQL
+      end
+
+      private
+
+      def ensure_tables
+        @db.execute(<<~SQL)
+          CREATE TABLE IF NOT EXISTS memories (
+            id              TEXT PRIMARY KEY,
+            project_path    TEXT NOT NULL,
+            tier            TEXT NOT NULL DEFAULT 'medium',
+            category        TEXT,
+            content         TEXT NOT NULL,
+            relevance_score REAL NOT NULL DEFAULT 1.0,
+            access_count    INTEGER NOT NULL DEFAULT 0,
+            last_accessed_at TEXT,
+            expires_at      TEXT,
+            metadata        TEXT DEFAULT '{}',
+            created_at      TEXT NOT NULL
+          )
+        SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_memories_project_tier
+          ON memories (project_path, tier)
+        SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_memories_project_category
+          ON memories (project_path, category)
+        SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_memories_expires_at
+          ON memories (expires_at) WHERE expires_at IS NOT NULL
+        SQL
+
+        # Search uses LIKE queries — no FTS table needed
+      end
+
+      # @param tier [String]
+      # @raise [ArgumentError]
+      def validate_tier!(tier)
+        return if VALID_TIERS.include?(tier)
+
+        raise ArgumentError, "Invalid tier: #{tier.inspect}. Must be one of: #{VALID_TIERS.join(', ')}"
+      end
+
+      # @param category [String]
+      # @raise [ArgumentError]
+      def validate_category!(category)
+        return if VALID_CATEGORIES.include?(category)
+
+        raise ArgumentError, "Invalid category: #{category.inspect}. Must be one of: #{VALID_CATEGORIES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rubyn_code/observability/budget_enforcer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require_relative "models"
+require_relative "cost_calculator"
+
+module RubynCode
+  module Observability
+    # Tracks API spend and halts the agent when session or daily budgets are
+    # exceeded. Cost records are persisted to SQLite so budgets survive restarts.
+    class BudgetEnforcer
+      DEFAULT_SESSION_LIMIT = 5.00
+      DEFAULT_DAILY_LIMIT   = 10.00
+
+      TABLE_NAME = "cost_records"
+
+      # @param db [DB::Connection] database connection
+      # @param session_id [String] current session identifier
+      # @param session_limit [Float] maximum USD spend per session
+      # @param daily_limit [Float] maximum USD spend per calendar day
+      def initialize(db, session_id:, session_limit: DEFAULT_SESSION_LIMIT, daily_limit: DEFAULT_DAILY_LIMIT)
+        @db            = db
+        @session_id    = session_id
+        @session_limit = session_limit.to_f
+        @daily_limit   = daily_limit.to_f
+
+        ensure_table_exists
+      end
+
+      # Records a cost entry for an API call and persists it to the database.
+      #
+      # @param model [String] the model identifier
+      # @param input_tokens [Integer] input token count
+      # @param output_tokens [Integer] output token count
+      # @param cache_read_tokens [Integer] cache-read token count
+      # @param cache_write_tokens [Integer] cache-write token count
+      # @param request_type [String] the type of request (e.g., "chat", "compact")
+      # @return [CostRecord] the persisted cost record
+      def record!(model:, input_tokens:, output_tokens:, cache_read_tokens: 0, cache_write_tokens: 0, request_type: "chat")
+        cost = CostCalculator.calculate(
+          model: model,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          cache_read_tokens: cache_read_tokens,
+          cache_write_tokens: cache_write_tokens
+        )
+
+        id = SecureRandom.uuid
+        now = Time.now.utc.iso8601
+
+        @db.execute(
+          "INSERT INTO #{TABLE_NAME} (id, session_id, model, input_tokens, output_tokens, " \
+          "cache_read_tokens, cache_write_tokens, cost_usd, request_type, created_at) " \
+          "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+          [id, @session_id, model, input_tokens, output_tokens,
+           cache_read_tokens, cache_write_tokens, cost, request_type, now]
+        )
+
+        CostRecord.new(
+          id: id,
+          session_id: @session_id,
+          model: model,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          cache_read_tokens: cache_read_tokens,
+          cache_write_tokens: cache_write_tokens,
+          cost_usd: cost,
+          request_type: request_type,
+          created_at: now
+        )
+      end
+
+      # Raises BudgetExceededError if either the session or daily budget is exceeded.
+      #
+      # @raise [BudgetExceededError] when spend exceeds a limit
+      # @return [void]
+      def check!
+        sc = session_cost
+        if sc >= @session_limit
+          raise BudgetExceededError,
+                "Session budget exceeded: $#{"%.4f" % sc} >= $#{"%.2f" % @session_limit} limit"
+        end
+
+        dc = daily_cost
+        if dc >= @daily_limit
+          raise BudgetExceededError,
+                "Daily budget exceeded: $#{"%.4f" % dc} >= $#{"%.2f" % @daily_limit} limit"
+        end
+      end
+
+      # Returns the total cost accumulated in the current session.
+      #
+      # @return [Float] total session cost in USD
+      def session_cost
+        rows = @db.query(
+          "SELECT COALESCE(SUM(cost_usd), 0.0) AS total FROM #{TABLE_NAME} WHERE session_id = ?",
+          [@session_id]
+        ).to_a
+        extract_total(rows)
+      end
+
+      # Returns the total cost accumulated today (UTC).
+      #
+      # @return [Float] total daily cost in USD
+      def daily_cost
+        today = Time.now.utc.strftime("%Y-%m-%d")
+        rows = @db.query(
+          "SELECT COALESCE(SUM(cost_usd), 0.0) AS total FROM #{TABLE_NAME} WHERE created_at >= ?",
+          ["#{today}T00:00:00Z"]
+        ).to_a
+        extract_total(rows)
+      end
+
+      # Returns the smaller of the session and daily remaining budgets.
+      #
+      # @return [Float] remaining budget in USD
+      def remaining_budget
+        session_remaining = @session_limit - session_cost
+        daily_remaining   = @daily_limit - daily_cost
+        [session_remaining, daily_remaining].min
+      end
+
+      private
+
+      def ensure_table_exists
+        @db.execute(<<~SQL)
+          CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+            id TEXT PRIMARY KEY,
+            session_id TEXT NOT NULL,
+            model TEXT NOT NULL,
+            input_tokens INTEGER NOT NULL DEFAULT 0,
+            output_tokens INTEGER NOT NULL DEFAULT 0,
+            cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+            cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+            cost_usd REAL NOT NULL DEFAULT 0.0,
+            request_type TEXT NOT NULL DEFAULT 'chat',
+            created_at TEXT NOT NULL
+          )
+        SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_cost_records_session_id ON #{TABLE_NAME} (session_id)
+        SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_cost_records_created_at ON #{TABLE_NAME} (created_at)
+        SQL
+      end
+
+      def extract_total(rows)
+        return 0.0 if rows.nil? || rows.empty?
+
+        row = rows.first
+        (row["total"] || row[:total] || 0.0).to_f
+      end
+    end
+  end
+end

data/lib/rubyn_code/observability/cost_calculator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Observability
+    # Maps model identifiers and token counts to USD cost.
+    #
+    # Pricing is based on per-million-token rates. Cache reads are billed at
+    # 10% of the input rate; cache writes at 25% of the input rate.
+    module CostCalculator
+      # Per-million-token rates: { model_prefix => [input_rate, output_rate] }
+      PRICING = {
+        "claude-haiku-4-5"        => [1.00, 5.00],
+        "claude-sonnet-4-20250514" => [3.00, 15.00],
+        "claude-opus-4-20250514"   => [15.00, 75.00]
+      }.freeze
+
+      CACHE_READ_DISCOUNT  = 0.1
+      CACHE_WRITE_PREMIUM  = 1.25
+
+      class << self
+        # Calculates the USD cost for a single API call.
+        #
+        # @param model [String] the model identifier (exact or prefix match)
+        # @param input_tokens [Integer] number of input tokens
+        # @param output_tokens [Integer] number of output tokens
+        # @param cache_read_tokens [Integer] tokens served from cache
+        # @param cache_write_tokens [Integer] tokens written to cache
+        # @return [Float] cost in USD
+        def calculate(model:, input_tokens:, output_tokens:, cache_read_tokens: 0, cache_write_tokens: 0)
+          input_rate, output_rate = rates_for(model)
+
+          input_cost       = (input_tokens.to_f / 1_000_000) * input_rate
+          output_cost      = (output_tokens.to_f / 1_000_000) * output_rate
+          cache_read_cost  = (cache_read_tokens.to_f / 1_000_000) * input_rate * CACHE_READ_DISCOUNT
+          cache_write_cost = (cache_write_tokens.to_f / 1_000_000) * input_rate * CACHE_WRITE_PREMIUM
+
+          input_cost + output_cost + cache_read_cost + cache_write_cost
+        end
+
+        private
+
+        # Resolves pricing rates for a model, falling back to prefix matching
+        # and then a conservative default.
+        #
+        # @param model [String]
+        # @return [Array(Float, Float)] [input_rate, output_rate]
+        def rates_for(model)
+          return PRICING[model] if PRICING.key?(model)
+
+          # Try prefix match (e.g., "claude-sonnet-4-20250514-v2" matches "claude-sonnet-4-20250514")
+          PRICING.each do |prefix, rates|
+            return rates if model.start_with?(prefix)
+          end
+
+          # Conservative fallback: use the most expensive known model
+          PRICING.max_by { |_, rates| rates.first }.last
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/observability/models.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Observability
+    # Immutable record of a single API call's cost, stored in the database.
+    CostRecord = Data.define(
+      :id,
+      :session_id,
+      :model,
+      :input_tokens,
+      :output_tokens,
+      :cache_read_tokens,
+      :cache_write_tokens,
+      :cost_usd,
+      :request_type,
+      :created_at
+    )
+
+    # Snapshot of metrics for a single agent turn (request/response cycle).
+    TurnMetrics = Data.define(
+      :model,
+      :input_tokens,
+      :output_tokens,
+      :cost_usd,
+      :duration_ms,
+      :tool_calls_count
+    )
+  end
+end

data/lib/rubyn_code/observability/token_counter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubynCode
+  module Observability
+    # Estimates token counts from text using a character-based heuristic.
+    #
+    # This provides a fast approximation (~4 characters per token) suitable for
+    # budget tracking and context-window management. For exact counts, use the
+    # API's reported usage fields instead.
+    module TokenCounter
+      # Average characters per token for English text and source code.
+      CHARS_PER_TOKEN = 4
+
+      class << self
+        # Estimates the token count for a given string.
+        #
+        # @param text [String, nil] the text to estimate
+        # @return [Integer] estimated token count (minimum 0)
+        def estimate(text)
+          return 0 if text.nil? || text.empty?
+
+          (text.bytesize.to_f / CHARS_PER_TOKEN).ceil
+        end
+
+        # Estimates the token count for an array of messages by serializing
+        # them to JSON first. Accounts for the structural overhead of message
+        # formatting (role tags, separators, etc.).
+        #
+        # @param messages [Array<Hash>] messages in the API conversation format
+        # @return [Integer] estimated token count (minimum 0)
+        def estimate_messages(messages)
+          return 0 if messages.nil? || messages.empty?
+
+          json = JSON.generate(messages)
+          estimate(json)
+        end
+      end
+    end
+  end
+end