ask-state-providers 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 18cfafbe7783b55543313b0708ed885275c8bd954a63cf152251dbfb465fde49
+  data.tar.gz: 60c56b1e649b86c893e8af07b446c3a022afb4d4b56d0419d74465b402ca36be
+SHA512:
+  metadata.gz: 38f53d279574b58eddf256975467c8bb30047060e5e994093f38ced15feb61c7e02e34c9023b7ec02a669e1b94142ca9a26cdd9d27938c5f5d51aee5d61e0715
+  data.tar.gz: be37ac572c9081ab10bf85f878a6285fd04b3522c731ae0bc28d472c855584e567d791b21953f6e013df1cbf5ebe3c48146ba91aded39c4aa08e2e2c80456f1e

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] — 2026-07-23
+
+### Changed
+
+- **BREAKING:** Removed `SessionPersistence` wrapper class — no longer needed. Session accepts `State::Adapter` directly via `state:` keyword.
+- **BREAKING:** `Session.load` now calls `adapter.get(id)` instead of `adapter.load(id)`. Any custom adapter must respond to `get`/`set`/`delete`.
+
+### Added
+
+- **Shared contract test suite** — `AdapterContract` module with 26 tests that every backend must pass. Runs against SQLite, Redis (via fakeredis), Postgres (when `DATABASE_URL` is set), and MySQL (when `MYSQL_URL` is set).
+- **Per-turn persistence** — Session now persists after every LLM turn, not just at the end of `run()`. Mid-session crashes no longer lose progress.
+- **`Session.load` restores `@messages`** — Previously `session.messages` returned `nil` after loading. Now it's populated from the restored chat messages.
+
+### Fixed
+
+- **README** — Updated `persistence:` example to `state:`.
+
+## [0.1.0] — 2026-07-23
+
+### Added
+
+- **`Ask::State::Providers::SQLite`** — Persistent key-value store backed by SQLite with WAL mode. Supports all `Adapter` primitives: key-value (get/set/delete/set_if_not_exists/clear, TTL), distributed locking (acquire/release with token safety), message queues (FIFO enqueue/dequeue/depth), and ordered lists (append/range/remove with max-length trimming). 58 tests.
+
+- **`Ask::State::Providers::Redis`** — Distributed state store backed by Redis with `ask:state:` key namespace. Uses `SET NX EX` for atomic locking, `RPUSH`/`LPOP` for queues, `LTRIM` for bounded lists, and Lua `EVAL` for safe lock release. 40 tests (tested with fakeredis).
+
+- **`Ask::State::Providers::PostgreSQL`** — State store backed by PostgreSQL with connection pooling, `ON CONFLICT` handling, and `RETURNING` clauses. Tests skip gracefully when `DATABASE_URL` is not set.
+
+- **`Ask::State::Providers::MySQL`** — State store backed by MySQL/MariaDB with prepared statements and `ON DUPLICATE KEY UPDATE`. Tests skip gracefully when `MYSQL_URL` is not set.
+
+- **Autoloading** — All providers use Ruby `autoload` so only the backends you need are loaded.
+
+- **CI** — GitHub Actions workflow testing Ruby 3.2, 3.3, and 3.4.
+
+- **Documentation** — Full README with quick start, backend comparison table, and API reference.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# ask-state-providers
+
+Pluggable state backends for the [ask-rb](https://github.com/ask-rb) ecosystem. Provides `Ask::State::Adapter` implementations for **SQLite**, **Redis**, **PostgreSQL**, and **MySQL** — one interface, four databases, zero coupling to your infrastructure.
+
+```ruby
+# Local dev — zero config
+store = Ask::State::Providers::SQLite.new
+
+# In production with Rails
+store = Ask::State::Providers::Redis.new(url: ENV["REDIS_URL"])
+
+# With your existing database
+store = Ask::State::Providers::Postgres.new(url: ENV["DATABASE_URL"])
+```
+
+## Why?
+
+ask-rb agents and sessions need to persist state — conversations, tool results, locks, task queues. Each deployment has different infrastructure: a CLI tool needs SQLite, a Rails app already has Postgres, a distributed system needs Redis. Instead of baking one backend into ask-core, this gem provides them all as drop-in adapters behind the same `Ask::State::Adapter` contract.
+
+## Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+gem "ask-state-providers"
+```
+
+Then add the database driver for the backend you want to use:
+
+```ruby
+# For SQLite (ships with Ruby's standard library — no extra gem needed on most systems)
+gem "sqlite3"
+
+# For Redis
+gem "redis"
+
+# For PostgreSQL
+gem "pg"
+
+# For MySQL
+gem "mysql2"
+```
+
+## Quick Start
+
+```ruby
+require "ask-state-providers"
+
+# Pick your backend:
+store = Ask::State::Providers::SQLite.new(path: "my_app.db")
+# store = Ask::State::Providers::Redis.new(url: ENV["REDIS_URL"])
+# store = Ask::State::Providers::Postgres.new(url: ENV["DATABASE_URL"])
+# store = Ask::State::Providers::MySQL.new(url: ENV["MYSQL_URL"])
+
+# Key-value storage
+store.set("user:1", { name: "Alice", role: "admin" })
+store.get("user:1")         # => {"name" => "Alice", "role" => "admin"}
+store.set("temp", "expires", ttl: 3600)  # auto-expires in 1 hour
+store.delete("user:1")
+
+# Conditional create
+store.set_if_not_exists("lock:deploy", "in_progress")
+
+# Distributed locking
+lock = store.acquire_lock("deploy-prod", ttl: 60)
+store.release_lock("deploy-prod", lock) if lock
+
+# Message queues
+store.enqueue("tasks", { action: "send_email" })
+task = store.dequeue("tasks")
+
+# Ordered lists
+store.list_append("recent_events", event, max_length: 100)
+store.list_range("recent_events", 0, 9)  # first 10
+```
+
+## Backends
+
+### SQLite (`Ask::State::Providers::SQLite`)
+
+Best for single-process, single-user applications — CLI tools, local development, personal agents.
+
+| Feature | Detail |
+|---------|--------|
+| **Driver** | [`sqlite3`](https://github.com/sparklemotion/sqlite3-ruby) |
+| **Configuration** | `SQLite.new(path:)` |
+| **Storage** | Single file on disk |
+| **Concurrency** | WAL mode with 5-second busy timeout |
+| **Tables** | `state_store`, `locks`, `queues`, `lists` (auto-created) |
+
+Uses `INSERT OR REPLACE` for key-value, `INSERT ... WHERE NOT EXISTS` for conditional writes, and `DELETE ... RETURNING` for safe queue dequeue.
+
+### Redis (`Ask::State::Providers::Redis`)
+
+Best for distributed, multi-process, or multi-host deployments.
+
+| Feature | Detail |
+|---------|--------|
+| **Driver** | [`redis`](https://github.com/redis-rb/redis-rb) |
+| **Configuration** | `Redis.new(url:)` |
+| **Storage** | In-memory with optional persistence |
+| **Key prefix** | `ask:state:` (all keys are namespaced) |
+
+Leverages Redis-native primitives: `SET NX EX` for atomic locking with auto-expire, `RPUSH`/`LPOP` for FIFO queues, `LTRIM` for bounded lists, Lua `EVAL` for safe lock release.
+
+### PostgreSQL (`Ask::State::Providers::Postgres`)
+
+Best for Rails apps and deployments already running Postgres.
+
+| Feature | Detail |
+|---------|--------|
+| **Driver** | [`pg`](https://github.com/ged/ruby-pg) |
+| **Configuration** | `Postgres.new(url:)` |
+| **Connection pool** | Built-in via `connection_pool` (default pool size: 5) |
+
+Uses `ON CONFLICT`, `RETURNING`, and `INSERT ... WHERE NOT EXISTS` for safe concurrent access.
+
+### MySQL (`Ask::State::Providers::MySQL`)
+
+Best for teams already running MySQL or MariaDB.
+
+| Feature | Detail |
+|---------|--------|
+| **Driver** | [`mysql2`](https://github.com/brianmario/mysql2) |
+| **Configuration** | `MySQL.new(url:)` |
+| **Character set** | `utf8mb4` (full Unicode including emoji) |
+
+Uses prepared statements, `ON DUPLICATE KEY UPDATE`, and `SELECT ... LIMIT 1` for safe dequeue.
+
+## API Reference
+
+All backends implement `Ask::State::Adapter`:
+
+### Key-Value
+
+| Method | Description |
+|--------|-------------|
+| `get(key)` | Retrieve a value, or `nil` if missing or expired |
+| `set(key, value, ttl:)` | Store a value (JSON-serializable). `ttl` in seconds |
+| `delete(key)` | Remove a key |
+| `set_if_not_exists(key, value, ttl:)` | Create only if key doesn't exist (or is expired). Returns `true`/`false` |
+| `clear` | Remove all keys |
+
+### Distributed Locking
+
+| Method | Description |
+|--------|-------------|
+| `acquire_lock(key, ttl:)` | Acquire a lock. Returns `Lock` or `nil` |
+| `release_lock(key, lock)` | Release a lock (only the owner can). Returns `true`/`false` |
+
+### Message Queues
+
+| Method | Description |
+|--------|-------------|
+| `enqueue(queue, value)` | Push to the back of a queue. Returns `QueueEntry` |
+| `dequeue(queue)` | Pop from the front of a queue. Returns `QueueEntry` or `nil` |
+| `queue_depth(queue)` | Number of items in the queue |
+
+### Ordered Lists
+
+| Method | Description |
+|--------|-------------|
+| `list_append(key, value, max_length:)` | Append to list. Trims to `max_length` (keeps newest) |
+| `list_range(key, start, stop)` | Slice of the list. `stop = -1` means all |
+| `list_remove(key, value)` | Remove all occurrences. Returns count removed |
+
+### Lifecycle
+
+| Method | Description |
+|--------|-------------|
+| `close` | Close the connection(s) |
+
+## Using with ask-agent Sessions
+
+```ruby
+require "ask-state-providers"
+require "ask-agent"
+
+store = Ask::State::Providers::SQLite.new
+
+session = Ask::Agent::Session.new(
+  "triage",
+  model: "gpt-4o",
+  state: store
+)
+
+session.run("What happened last time we saw this error?")
+# Every turn is persisted — survive restarts, searchable, auditable
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests (SQLite tests run everywhere, Redis needs fakeredis,
+# Postgres/MySQL need DATABASE_URL/MYSQL_URL env vars)
+bundle exec rake test
+
+# Run tests with verbose output
+bundle exec ruby -Itest test/ask/state/providers/sqlite_test.rb
+bundle exec ruby -Itest test/ask/state/providers/redis_test.rb
+
+# Test Postgres locally
+DATABASE_URL="postgres://localhost:5432/ask_state_test" bundle exec rake test
+
+# Test MySQL locally
+MYSQL_URL="mysql2://root@localhost:3306/ask_state_test" bundle exec rake test
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- **Source:** https://github.com/ask-rb/ask-state-providers
+- **Issues:** https://github.com/ask-rb/ask-state-providers/issues
+- **Docs:** https://github.com/ask-rb/ask-docs

data/lib/ask/state/providers/mysql.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "securerandom"
+
+module Ask
+  module State
+    module Providers
+      # A persistent key-value store backed by MySQL.
+      #
+      # Implements the full {Ask::State::Adapter} contract:
+      # key-value storage, distributed locking, message queues, and ordered
+      # lists. Uses the +mysql2+ gem for database access.
+      #
+      # @example
+      #   store = Ask::State::Providers::MySQL.new(
+      #     url: ENV["MYSQL_URL"]
+      #   )
+      #   store.set("key", { hello: "world" })
+      #   store.get("key")  # => { "hello" => "world" }
+      #
+      class MySQL < ::Ask::State::Adapter
+        MIGRATIONS = <<~SQL
+          CREATE TABLE IF NOT EXISTS state_store (
+            `key`       VARCHAR(255) PRIMARY KEY NOT NULL,
+            `value`     TEXT NOT NULL,
+            expires_at  DATETIME(3) NULL
+          ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+          CREATE TABLE IF NOT EXISTS locks (
+            `key`       VARCHAR(255) PRIMARY KEY NOT NULL,
+            token       VARCHAR(64) NOT NULL,
+            expires_at  DATETIME(3) NOT NULL
+          ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+          CREATE TABLE IF NOT EXISTS queues (
+            id           BIGINT AUTO_INCREMENT PRIMARY KEY,
+            queue_name   VARCHAR(255) NOT NULL,
+            `value`      TEXT NOT NULL,
+            enqueued_at  DATETIME(3) NOT NULL,
+            INDEX idx_queues_queue_name (queue_name, id)
+          ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+          CREATE TABLE IF NOT EXISTS lists (
+            id         BIGINT AUTO_INCREMENT PRIMARY KEY,
+            list_key   VARCHAR(255) NOT NULL,
+            `value`    TEXT NOT NULL,
+            INDEX idx_lists_list_key (list_key, id)
+          ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+        SQL
+
+        # Creates a new MySQL-backed state store.
+        #
+        # @param url [String] MySQL connection URL
+        def initialize(url: ENV.fetch("MYSQL_URL", "mysql2://root@localhost:3306/ask_state"))
+          require "mysql2"
+
+          uri = URI.parse(url)
+          @client = Mysql2::Client.new(
+            host: uri.host || "localhost",
+            port: uri.port || 3306,
+            username: uri.user || "root",
+            password: uri.password,
+            database: uri.path.sub("/", ""),
+            charset: "utf8mb4"
+          )
+
+          migrate
+        end
+
+        # -- key-value --
+
+        def get(key)
+          row = @client.prepare(<<~SQL).execute(key, Time.now.utc.strftime("%Y-%m-%d %H:%M:%S.%3N")).first
+            SELECT `value` FROM state_store
+            WHERE `key` = ? AND (expires_at IS NULL OR expires_at > ?)
+          SQL
+          row ? JSON.parse(row["value"]) : nil
+        end
+
+        def set(key, value, ttl: nil)
+          stmt = @client.prepare(<<~SQL)
+            INSERT INTO state_store (`key`, `value`, expires_at)
+            VALUES (?, ?, ?)
+            ON DUPLICATE KEY UPDATE
+              `value` = VALUES(`value`),
+              expires_at = VALUES(expires_at)
+          SQL
+          stmt.execute(key, JSON.generate(value), ttl ? (Time.now.utc + ttl).strftime("%Y-%m-%d %H:%M:%S.%3N") : nil)
+        end
+
+        def delete(key)
+          @client.prepare("DELETE FROM state_store WHERE `key` = ?").execute(key)
+        end
+
+        def set_if_not_exists(key, value, ttl: nil)
+          now = Time.now.utc
+          expires = ttl ? (now + ttl).strftime("%Y-%m-%d %H:%M:%S.%3N") : nil
+          now_f = now.strftime("%Y-%m-%d %H:%M:%S.%3N")
+
+          stmt = @client.prepare(<<~SQL)
+            INSERT INTO state_store (`key`, `value`, expires_at)
+            SELECT ?, ?, ?
+            WHERE NOT EXISTS (
+              SELECT 1 FROM state_store
+              WHERE `key` = ? AND (expires_at IS NULL OR expires_at > ?)
+            )
+          SQL
+          # MySQL's INSERT...SELECT won't fail on DUPLICATE KEY if WHERE is false
+          stmt.execute(key, JSON.generate(value), expires, key, now_f)
+          @client.affected_rows > 0
+        end
+
+        def clear
+          @client.query("DELETE FROM state_store")
+        end
+
+        # -- distributed locking --
+
+        def acquire_lock(key, ttl: 10)
+          now = Time.now.utc
+          expires_at_time = now + ttl
+          token = SecureRandom.hex(16)
+          now_f = now.strftime("%Y-%m-%d %H:%M:%S.%3N")
+
+          # Clean up expired lock
+          @client.prepare("DELETE FROM locks WHERE `key` = ? AND expires_at <= ?").execute(key, now_f)
+
+          result = @client.prepare(<<~SQL).execute(key, expires_at_time.strftime("%Y-%m-%d %H:%M:%S.%3N"), token)
+            INSERT INTO locks (`key`, expires_at, token)
+            SELECT ?, ?, ?
+            WHERE NOT EXISTS (
+              SELECT 1 FROM locks WHERE `key` = ?
+            )
+          SQL
+          result = @client.prepare(<<~SQL).execute(key)
+            SELECT COUNT(*) AS cnt FROM locks WHERE `key` = ?
+          SQL
+
+          # Check if we got the lock
+          row = result.first
+          return nil unless row && row["cnt"].to_i > 0
+
+          Lock.new(id: key, token: token, expires_at: expires_at_time)
+        end
+
+        def release_lock(key, lock)
+          @client.prepare("DELETE FROM locks WHERE `key` = ? AND token = ?").execute(key, lock.token)
+          @client.affected_rows > 0
+        end
+
+        # -- message queues --
+
+        def enqueue(queue, value)
+          stmt = @client.prepare(<<~SQL)
+            INSERT INTO queues (queue_name, `value`, enqueued_at)
+            VALUES (?, ?, ?)
+          SQL
+          stmt.execute(queue, JSON.generate(value), Time.now.utc.strftime("%Y-%m-%d %H:%M:%S.%3N"))
+          id = @client.last_id
+
+          QueueEntry.new(id: id.to_s, value: value, enqueued_at: Time.now)
+        end
+
+        def dequeue(queue)
+          row = @client.prepare(<<~SQL).execute(queue).first
+            SELECT id, `value`, enqueued_at FROM queues
+            WHERE queue_name = ?
+            ORDER BY id ASC
+            LIMIT 1
+          SQL
+          return nil unless row
+
+          @client.prepare("DELETE FROM queues WHERE id = ?").execute(row["id"])
+
+          QueueEntry.new(
+            id: row["id"].to_s,
+            value: JSON.parse(row["value"]),
+            enqueued_at: Time.parse(row["enqueued_at"])
+          )
+        end
+
+        def queue_depth(queue)
+          result = @client.prepare("SELECT COUNT(*) AS cnt FROM queues WHERE queue_name = ?").execute(queue)
+          row = result.first
+          row["cnt"]
+        end
+
+        # -- ordered lists --
+
+        def list_append(key, value, max_length: nil)
+          stmt = @client.prepare("INSERT INTO lists (list_key, `value`) VALUES (?, ?)")
+          stmt.execute(key, JSON.generate(value))
+
+          return unless max_length
+
+          @client.prepare(<<~SQL).execute(key, key, max_length)
+            DELETE FROM lists WHERE id <= (
+              SELECT COALESCE(MIN(id), 0) FROM (
+                SELECT id FROM lists
+                WHERE list_key = ?
+                ORDER BY id DESC
+                LIMIT ?
+              ) sub
+            )
+          SQL
+        end
+
+        def list_range(key, start = 0, stop = -1)
+          rows = if stop == -1
+            @client.prepare(<<~SQL).execute(key, start)
+              SELECT `value` FROM lists
+              WHERE list_key = ?
+              ORDER BY id ASC
+              LIMIT 18446744073709551615 OFFSET ?
+            SQL
+          else
+            limit = stop - start + 1
+            @client.prepare(<<~SQL).execute(key, limit, start)
+              SELECT `value` FROM lists
+              WHERE list_key = ?
+              ORDER BY id ASC
+              LIMIT ? OFFSET ?
+            SQL
+          end
+          rows.map { |r| JSON.parse(r["value"]) }
+        end
+
+        def list_remove(key, value)
+          serialized = JSON.generate(value)
+          @client.prepare("DELETE FROM lists WHERE list_key = ? AND `value` = ?").execute(key, serialized)
+          @client.affected_rows
+        end
+
+        # -- lifecycle --
+
+        def close
+          @client&.close
+        end
+
+        private
+
+        def migrate
+          MIGRATIONS.split(";").each do |sql|
+            sql = sql.strip
+            @client.query(sql) unless sql.empty?
+          end
+        rescue => e
+          # Tables may already exist with different charset — that's fine
+          raise unless e.message.include?("already exists")
+        end
+      end
+    end
+  end
+end

data/lib/ask/state/providers/postgres.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "securerandom"
+
+module Ask
+  module State
+    module Providers
+      # A persistent key-value store backed by PostgreSQL.
+      #
+      # Implements the full {Ask::State::Adapter} contract:
+      # key-value storage, distributed locking, message queues, and ordered
+      # lists. Uses the +pg+ gem for database access.
+      #
+      # @example
+      #   store = Ask::State::Providers::Postgres.new(
+      #     url: ENV["DATABASE_URL"]
+      #   )
+      #   store.set("key", { hello: "world" })
+      #   store.get("key")  # => { "hello" => "world" }
+      #
+      class Postgres < ::Ask::State::Adapter
+        MIGRATIONS = <<~SQL
+          CREATE TABLE IF NOT EXISTS state_store (
+            key         TEXT PRIMARY KEY NOT NULL,
+            value       TEXT NOT NULL,
+            expires_at  TIMESTAMPTZ
+          );
+
+          CREATE TABLE IF NOT EXISTS locks (
+            key         TEXT PRIMARY KEY NOT NULL,
+            token       TEXT NOT NULL,
+            expires_at  TIMESTAMPTZ NOT NULL
+          );
+
+          CREATE TABLE IF NOT EXISTS queues (
+            id           BIGSERIAL PRIMARY KEY,
+            queue_name   TEXT NOT NULL,
+            value        TEXT NOT NULL,
+            enqueued_at  TIMESTAMPTZ NOT NULL
+          );
+          CREATE INDEX IF NOT EXISTS idx_queues_queue_name
+            ON queues (queue_name, id);
+
+          CREATE TABLE IF NOT EXISTS lists (
+            id         BIGSERIAL PRIMARY KEY,
+            list_key   TEXT NOT NULL,
+            value      TEXT NOT NULL
+          );
+          CREATE INDEX IF NOT EXISTS idx_lists_list_key
+            ON lists (list_key, id);
+        SQL
+
+        # Creates a new PostgreSQL-backed state store.
+        #
+        # @param url [String] Postgres connection URL
+        # @param pool_size [Integer] connection pool size (default 5)
+        def initialize(url: ENV.fetch("DATABASE_URL", "postgres://localhost:5432/ask_state"),
+                       pool_size: 5)
+          require "pg"
+
+          @pool = ConnectionPool.new(size: pool_size) do
+            ::PG.connect(url)
+          end
+
+          migrate
+        end
+
+        # -- key-value --
+
+        def get(key)
+          @pool.with do |conn|
+            row = conn.exec_params(<<~SQL, [key, Time.now.utc])
+              SELECT value FROM state_store
+              WHERE key = $1 AND (expires_at IS NULL OR expires_at > $2)
+            SQL
+            row.ntuples > 0 ? JSON.parse(row[0]["value"]) : nil
+          end
+        end
+
+        def set(key, value, ttl: nil)
+          @pool.with do |conn|
+            conn.exec_params(<<~SQL, [key, JSON.generate(value), ttl ? Time.now.utc + ttl : nil])
+              INSERT INTO state_store (key, value, expires_at)
+              VALUES ($1, $2, $3)
+              ON CONFLICT (key) DO UPDATE SET
+                value = EXCLUDED.value,
+                expires_at = EXCLUDED.expires_at
+            SQL
+          end
+        end
+
+        def delete(key)
+          @pool.with do |conn|
+            conn.exec_params("DELETE FROM state_store WHERE key = $1", [key])
+          end
+        end
+
+        def set_if_not_exists(key, value, ttl: nil)
+          @pool.with do |conn|
+            now = Time.now.utc
+            expires = ttl ? now + ttl : nil
+
+            result = conn.exec_params(<<~SQL, [key, JSON.generate(value), expires, now])
+              INSERT INTO state_store (key, value, expires_at)
+              SELECT $1, $2, $3
+              WHERE NOT EXISTS (
+                SELECT 1 FROM state_store
+                WHERE key = $1 AND (expires_at IS NULL OR expires_at > $4)
+              )
+              ON CONFLICT (key) DO NOTHING
+            SQL
+            result.cmd_tuples > 0
+          end
+        end
+
+        def clear
+          @pool.with { |conn| conn.exec("DELETE FROM state_store") }
+        end
+
+        # -- distributed locking --
+
+        def acquire_lock(key, ttl: 10)
+          now = Time.now.utc
+          expires_at_time = now + ttl
+          token = SecureRandom.hex(16)
+
+          acquired = @pool.with do |conn|
+            # First clean up expired locks
+            conn.exec_params("DELETE FROM locks WHERE key = $1 AND expires_at <= $2",
+                           [key, now])
+
+            result = conn.exec_params(<<~SQL, [key, expires_at_time, token, now])
+              INSERT INTO locks (key, expires_at, token)
+              SELECT $1, $2, $3
+              WHERE NOT EXISTS (
+                SELECT 1 FROM locks
+                WHERE key = $1
+              )
+            SQL
+            result.cmd_tuples > 0
+          end
+
+          acquired ? Lock.new(id: key, token: token, expires_at: expires_at_time) : nil
+        end
+
+        def release_lock(key, lock)
+          @pool.with do |conn|
+            result = conn.exec_params(
+              "DELETE FROM locks WHERE key = $1 AND token = $2",
+              [key, lock.token]
+            )
+            result.cmd_tuples > 0
+          end
+        end
+
+        # -- message queues --
+
+        def enqueue(queue, value)
+          id = SecureRandom.uuid
+
+          @pool.with do |conn|
+            conn.exec_params(<<~SQL, [queue, JSON.generate(value), Time.now.utc])
+              INSERT INTO queues (queue_name, value, enqueued_at)
+              VALUES ($1, $2, $3)
+            SQL
+          end
+
+          QueueEntry.new(id: id, value: value, enqueued_at: Time.now)
+        end
+
+        def dequeue(queue)
+          @pool.with do |conn|
+            result = conn.exec_params(<<~SQL, [queue])
+              DELETE FROM queues
+              WHERE id = (
+                SELECT id FROM queues
+                WHERE queue_name = $1
+                ORDER BY id ASC
+                LIMIT 1
+              )
+              RETURNING value, enqueued_at
+            SQL
+            return nil if result.ntuples == 0
+
+            QueueEntry.new(
+              id: SecureRandom.uuid,
+              value: JSON.parse(result[0]["value"]),
+              enqueued_at: Time.parse(result[0]["enqueued_at"])
+            )
+          end
+        end
+
+        def queue_depth(queue)
+          @pool.with do |conn|
+            result = conn.exec_params(
+              "SELECT COUNT(*) AS cnt FROM queues WHERE queue_name = $1", [queue]
+            )
+            result[0]["cnt"].to_i
+          end
+        end
+
+        # -- ordered lists --
+
+        def list_append(key, value, max_length: nil)
+          @pool.with do |conn|
+            conn.exec_params(<<~SQL, [key, JSON.generate(value)])
+              INSERT INTO lists (list_key, value)
+              VALUES ($1, $2)
+            SQL
+
+            return unless max_length
+
+            conn.exec_params(<<~SQL, [key, key, max_length])
+              DELETE FROM lists WHERE id <= (
+                SELECT COALESCE(MIN(id), 0) FROM (
+                  SELECT id FROM lists
+                  WHERE list_key = $1
+                  ORDER BY id DESC
+                  LIMIT $3
+                ) sub
+              )
+            SQL
+          end
+        end
+
+        def list_range(key, start = 0, stop = -1)
+          @pool.with do |conn|
+            rows = if stop == -1
+              conn.exec_params(<<~SQL, [key, start])
+                SELECT value FROM lists
+                WHERE list_key = $1
+                ORDER BY id ASC
+                OFFSET $2
+              SQL
+            else
+              limit = stop - start + 1
+              conn.exec_params(<<~SQL, [key, limit, start])
+                SELECT value FROM lists
+                WHERE list_key = $1
+                ORDER BY id ASC
+                LIMIT $2 OFFSET $3
+              SQL
+            end
+            rows.map { |r| JSON.parse(r["value"]) }
+          end
+        end
+
+        def list_remove(key, value)
+          serialized = JSON.generate(value)
+          @pool.with do |conn|
+            result = conn.exec_params(
+              "DELETE FROM lists WHERE list_key = $1 AND value = $2",
+              [key, serialized]
+            )
+            result.cmd_tuples
+          end
+        end
+
+        # -- lifecycle --
+
+        def close
+          @pool&.shutdown { |c| c.close }
+        end
+
+        private
+
+        def migrate
+          @pool.with { |conn| conn.exec(MIGRATIONS) }
+        end
+      end
+    end
+  end
+end

data/lib/ask/state/providers/redis.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Ask
+  module State
+    module Providers
+      # A distributed key-value store backed by Redis.
+      #
+      # Implements the full {Ask::State::Adapter} contract:
+      # key-value storage, distributed locking, message queues, and ordered
+      # lists. Best suited for multi-process or multi-host deployments where
+      # shared state is required.
+      #
+      # @example
+      #   store = Ask::State::Providers::Redis.new(url: ENV["REDIS_URL"])
+      #   store.set("key", { hello: "world" })
+      #   store.get("key")  # => { "hello" => "world" }
+      #
+      class Redis < ::Ask::State::Adapter
+        NAMESPACE = "ask:state"
+
+        # Creates a new Redis-backed state store.
+        #
+        # @param url [String] Redis URL (redis://...)
+        def initialize(url: ENV.fetch("REDIS_URL", "redis://localhost:6379"))
+          require "redis"
+
+          @redis = ::Redis.new(url: url)
+        end
+
+        # -- key-value --
+
+        def get(key)
+          val = @redis.call("GET", prefixed(key))
+          val ? JSON.parse(val) : nil
+        end
+
+        def set(key, value, ttl: nil)
+          args = [prefixed(key), JSON.generate(value)]
+          args.concat(["EX", ttl.to_i]) if ttl
+          @redis.call("SET", *args)
+        end
+
+        def delete(key)
+          @redis.call("DEL", prefixed(key))
+        end
+
+        def set_if_not_exists(key, value, ttl: nil)
+          args = [prefixed(key), JSON.generate(value)]
+          args.concat(["EX", ttl.to_i]) if ttl
+          @redis.call("SET", *args, "NX") == "OK"
+        end
+
+        def clear
+          keys = @redis.call("KEYS", "#{NAMESPACE}:*")
+          @redis.call("DEL", *keys) if keys.any?
+        end
+
+        # -- distributed locking --
+
+        def acquire_lock(key, ttl: 10)
+          prefixed_key = prefixed("lock:#{key}")
+          token = SecureRandom.hex(16)
+          expires_at = Time.now + ttl
+
+          acquired = @redis.call("SET", prefixed_key, token, "NX", "EX", ttl) == "OK"
+          acquired ? Lock.new(id: key, token: token, expires_at: expires_at) : nil
+        end
+
+        def release_lock(key, lock)
+          prefixed_key = prefixed("lock:#{key}")
+
+          # Atomic release: only delete if token matches (Lua script)
+          script = <<~LUA
+            if redis.call("GET", KEYS[1]) == ARGV[1] then
+              return redis.call("DEL", KEYS[1])
+            else
+              return 0
+            end
+          LUA
+
+          @redis.call("EVAL", script, [1], [prefixed_key, lock.token]) == 1
+        end
+
+        # -- message queues --
+
+        def enqueue(queue, value)
+          id = SecureRandom.uuid
+          entry = { id: id, value: value, enqueued_at: Time.now.iso8601 }
+
+          @redis.call("RPUSH", prefixed("queue:#{queue}"), JSON.generate(entry))
+
+          QueueEntry.new(id: id, value: value, enqueued_at: Time.now)
+        end
+
+        def dequeue(queue)
+          val = @redis.call("LPOP", prefixed("queue:#{queue}"))
+          return nil unless val
+
+          entry = JSON.parse(val)
+          QueueEntry.new(
+            id: entry["id"],
+            value: entry["value"],
+            enqueued_at: Time.parse(entry["enqueued_at"])
+          )
+        end
+
+        def queue_depth(queue)
+          @redis.call("LLEN", prefixed("queue:#{queue}"))
+        end
+
+        # -- ordered lists --
+
+        def list_append(key, value, max_length: nil)
+          @redis.call("RPUSH", prefixed("list:#{key}"), JSON.generate(value))
+          return unless max_length
+
+          # LTRIM keeps only the specified range (negative indices, so -max_length means keep newest max_length)
+          @redis.call("LTRIM", prefixed("list:#{key}"), -max_length, -1)
+        end
+
+        def list_range(key, start = 0, stop = -1)
+          items = @redis.call("LRANGE", prefixed("list:#{key}"), start, stop)
+          items.map { |item| JSON.parse(item) }
+        end
+
+        def list_remove(key, value)
+          serialized = JSON.generate(value)
+          @redis.call("LREM", prefixed("list:#{key}"), 0, serialized)
+        end
+
+        # -- lifecycle --
+
+        def close
+          @redis&.close
+        end
+
+        private
+
+        def prefixed(key)
+          "#{NAMESPACE}:#{key}"
+        end
+      end
+    end
+  end
+end

data/lib/ask/state/providers/sqlite.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "securerandom"
+
+module Ask
+  module State
+    module Providers
+      # A persistent key-value store backed by SQLite.
+      #
+      # Implements the full {Ask::State::Adapter} contract:
+      # key-value storage, distributed locking, message queues, and ordered
+      # lists. Uses the +sqlite3+ gem.
+      #
+      # @example
+      #   store = Ask::State::Providers::SQLite.new(path: "sessions.db")
+      #   store.set("key", { hello: "world" })
+      #   store.get("key")  # => { "hello" => "world" }
+      #
+      class SQLite < ::Ask::State::Adapter
+        # Creates or opens the database at +path+.
+        def initialize(path: "sessions.db", **pragmas)
+          require "sqlite3"
+
+          @db = SQLite3::Database.new(path)
+          @db.results_as_hash = true
+          @db.busy_timeout = 5000
+
+          defaults = {
+            journal_mode: "WAL",
+            synchronous: "NORMAL",
+            foreign_keys: "ON",
+            cache_size: -64_000
+          }
+
+          defaults.merge(pragmas).each do |key, value|
+            @db.execute("PRAGMA #{key} = #{value}")
+          end
+
+          migrate
+        end
+
+        # -- key-value --
+
+        def get(key)
+          row = @db.get_first_row(<<~SQL, [key, Time.now.to_f])
+            SELECT value FROM state_store
+            WHERE key = ? AND (expires_at IS NULL OR expires_at > ?)
+          SQL
+          row ? JSON.parse(row["value"]) : nil
+        end
+
+        def set(key, value, ttl: nil)
+          @db.execute(<<~SQL, [key, JSON.generate(value), ttl ? Time.now.to_f + ttl : nil])
+            INSERT OR REPLACE INTO state_store (key, value, expires_at)
+            VALUES (?, ?, ?)
+          SQL
+        end
+
+        def delete(key)
+          @db.execute("DELETE FROM state_store WHERE key = ?", [key])
+        end
+
+        def set_if_not_exists(key, value, ttl: nil)
+          now = Time.now.to_f
+          expires = ttl ? now + ttl : nil
+
+          @db.transaction do
+            row = @db.get_first_row(
+              "SELECT 1 FROM state_store WHERE key = ? AND (expires_at IS NULL OR expires_at > ?)",
+              [key, now]
+            )
+            next false if row
+
+            @db.execute("DELETE FROM state_store WHERE key = ?", [key])
+            @db.execute(<<~SQL, [key, JSON.generate(value), expires])
+              INSERT INTO state_store (key, value, expires_at)
+              VALUES (?, ?, ?)
+            SQL
+            next true
+          end
+        end
+
+        def clear
+          @db.execute("DELETE FROM state_store")
+        end
+
+        # -- distributed locking --
+
+        def acquire_lock(key, ttl: 10)
+          now = Time.now.to_f
+          expires_at_time = Time.now + ttl
+          token = SecureRandom.hex(16)
+
+          acquired = @db.transaction do
+            row = @db.get_first_row(
+              "SELECT 1 FROM locks WHERE key = ? AND expires_at > ?",
+              [key, now]
+            )
+            next false if row
+
+            @db.execute("DELETE FROM locks WHERE key = ?", [key])
+            @db.execute(<<~SQL, [key, expires_at_time.to_f, token])
+              INSERT INTO locks (key, expires_at, token)
+              VALUES (?, ?, ?)
+            SQL
+            next true
+          end
+
+          acquired ? Lock.new(id: key, token: token, expires_at: expires_at_time) : nil
+        end
+
+        def release_lock(key, lock)
+          @db.execute(
+            "DELETE FROM locks WHERE key = ? AND token = ?",
+            [key, lock.token]
+          )
+          @db.changes > 0
+        end
+
+        # -- message queues --
+
+        def enqueue(queue, value)
+          @db.execute(<<~SQL, [queue, JSON.generate(value), Time.now.iso8601])
+            INSERT INTO queues (queue_name, value, enqueued_at)
+            VALUES (?, ?, ?)
+          SQL
+          id = @db.last_insert_row_id
+          QueueEntry.new(id: id.to_s, value: value, enqueued_at: Time.now)
+        end
+
+        def dequeue(queue)
+          row = @db.get_first_row(<<~SQL, [queue])
+            DELETE FROM queues
+            WHERE id = (
+              SELECT id FROM queues
+              WHERE queue_name = ?
+              ORDER BY id ASC
+              LIMIT 1
+            )
+            RETURNING id, value, enqueued_at
+          SQL
+          return nil unless row
+
+          QueueEntry.new(
+            id: row["id"].to_s,
+            value: JSON.parse(row["value"]),
+            enqueued_at: Time.parse(row["enqueued_at"])
+          )
+        end
+
+        def queue_depth(queue)
+          row = @db.get_first_row(
+            "SELECT COUNT(*) AS cnt FROM queues WHERE queue_name = ?", [queue]
+          )
+          row["cnt"]
+        end
+
+        # -- ordered lists --
+
+        def list_append(key, value, max_length: nil)
+          serialized = JSON.generate(value)
+
+          @db.execute(<<~SQL, [key, serialized])
+            INSERT INTO lists (list_key, value)
+            VALUES (?, ?)
+          SQL
+
+          return unless max_length
+
+          # Keep only the newest max_length items by deleting those with the
+          # smallest id values beyond the threshold
+          row = @db.get_first_row(<<~SQL, [key, max_length])
+            SELECT MIN(id) AS cutoff FROM (
+              SELECT id FROM lists
+              WHERE list_key = ?
+              ORDER BY id DESC
+              LIMIT ?
+            )
+          SQL
+          return unless row && row["cutoff"]
+
+          @db.execute(<<~SQL, [key, row["cutoff"]])
+            DELETE FROM lists WHERE list_key = ? AND id < ?
+          SQL
+        end
+
+        def list_range(key, start = 0, stop = -1)
+          if stop == -1
+            rows = @db.execute(<<~SQL, [key, start])
+              SELECT value FROM lists
+              WHERE list_key = ?
+              ORDER BY id ASC
+              LIMIT -1 OFFSET ?
+            SQL
+          else
+            limit = stop - start + 1
+            rows = @db.execute(<<~SQL, [key, limit, start])
+              SELECT value FROM lists
+              WHERE list_key = ?
+              ORDER BY id ASC
+              LIMIT ? OFFSET ?
+            SQL
+          end
+          rows.map { |r| JSON.parse(r["value"]) }
+        end
+
+        def list_remove(key, value)
+          serialized = JSON.generate(value)
+          @db.execute(
+            "DELETE FROM lists WHERE list_key = ? AND value = ?",
+            [key, serialized]
+          )
+          @db.changes
+        end
+
+        # -- lifecycle --
+
+        def close
+          @db.close
+        end
+
+        private
+
+        def migrate
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS state_store (
+              key         TEXT PRIMARY KEY NOT NULL,
+              value       TEXT NOT NULL,
+              expires_at  REAL
+            );
+
+            CREATE TABLE IF NOT EXISTS locks (
+              key         TEXT PRIMARY KEY NOT NULL,
+              token       TEXT NOT NULL,
+              expires_at  REAL NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS queues (
+              id           INTEGER PRIMARY KEY AUTOINCREMENT,
+              queue_name   TEXT NOT NULL,
+              value        TEXT NOT NULL,
+              enqueued_at  TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_queues_queue_name
+              ON queues (queue_name, id);
+
+            CREATE TABLE IF NOT EXISTS lists (
+              id         INTEGER PRIMARY KEY AUTOINCREMENT,
+              list_key   TEXT NOT NULL,
+              value      TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_lists_list_key
+              ON lists (list_key, id);
+          SQL
+        end
+      end
+    end
+  end
+end

data/lib/ask/state/providers/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ask
+  module State
+    module Providers
+      VERSION = "0.2.0"
+    end
+  end
+end

data/lib/ask-state-providers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "ask"
+require "ask/state"
+
+module Ask
+  module State
+    module Providers
+      autoload :SQLite,    "ask/state/providers/sqlite"
+      autoload :Redis,     "ask/state/providers/redis"
+      autoload :Postgres,  "ask/state/providers/postgres"
+      autoload :MySQL,     "ask/state/providers/mysql"
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: ask-state-providers
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides Ask::State adapter implementations for SQLite, Redis, PostgreSQL,
+  and MySQL. Each backend implements the Ask::State::Adapter contract (get/set/delete,
+  distributed locking, message queues, and ordered lists) so agents, sessions, and
+  workflows pick the right persistence layer with one line of code.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-state-providers.rb
+- lib/ask/state/providers/mysql.rb
+- lib/ask/state/providers/postgres.rb
+- lib/ask/state/providers/redis.rb
+- lib/ask/state/providers/sqlite.rb
+- lib/ask/state/providers/version.rb
+homepage: https://github.com/ask-rb/ask-state-providers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-state-providers
+  source_code_uri: https://github.com/ask-rb/ask-state-providers
+  changelog_uri: https://github.com/ask-rb/ask-state-providers/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Pluggable state backends for the ask-rb ecosystem
+test_files: []