ask-session 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ce03eac4e879e1e478ee60d22b6f30b374c05c6e35a5a88fc0566c58e972a09b
+  data.tar.gz: b47546ef122d601885718f767c7c778aaac8e89d59d835401e9865de12f3743d
+SHA512:
+  metadata.gz: 4f6fd701a98a0e6f98259bdeb2b5299bbba3ba76cc3d3a617e795f61e4d341f697c491d068663efb86e10362eec4a80588953704afc91166d55e9022e75802e3
+  data.tar.gz: d3b0922f243b949ee8062608c016cc99388fabe16f547e53fe5a876cdc73bd547c972e0fe2c5f5b74e611bd3ce93a867318114e1bc43de9e09eb440f9afb8f77

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-22
+
+### Added
+
+- `Ask::Session::Record` — immutable value object for session snapshots.
+- `Ask::Session::Event` — immutable event envelope with sequence, type, and causation.
+- `Ask::Session::Store` — in-memory store with concurrency guardrails.
+- `Ask::Session::State` — pure reducer that reconstructs session state from events.
+- `Ask::Session::ConcurrencyError` — dedicated error for sequence mismatches.
+- `Ask::Session::SerializationError` — dedicated error for malformed/missing-field JSON.
+- `Ask::Session::NotFoundError` — dedicated error when a session id does not exist.
+- `Ask::Session::DuplicateSessionError` — dedicated error when creating or importing a session id that already exists.
+- `Store#load!` — loads a session or raises `NotFoundError`.
+- `Store#current_sequence` — current event count for a session.
+- `Record#to_h` / `Record.from_h` — portable hash serialization with ISO8601 timestamps.
+- `Event#to_h` / `Event.from_h` — portable hash serialization with ISO8601 timestamps.
+- `Ask::Session::Codec` — JSON dump/load for Record and Event.
+- `Store#events` — returns a frozen array of all events for a session.
+- `Store#export` / `Store#import` — full session portability with duplicate and sequence validation.
+- `Store#state(session_id)` — reconstructs session state from stored events via the reducer.
+- `Store#export(session_id)` — exports a single session payload for targeted import.
+- `Store#import` — accepts both all-sessions and single-session shapes; validates atomically before mutating.
+- `Store#events_after` — now returns a frozen array snapshot.
+- `Ask::Session::Host` — replayable session host with create, session, list, events, send_message, close, abort, subscribe, and publish-subscribe.
+- `Host#append(session_id, type:, payload:, trace_id:, causation_id:)` — generic event append for arbitrary event types (tool calls, vendor webhooks, custom lifecycle events) without coupling ask-session to any protocol or agent gem.
+- `Ask::Session::ProviderStore` — durable store backed by any adapter responding to `get`, `set`, and `delete` (e.g. the ask-state-providers SQLite/Redis/Postgres/MySQL adapters): namespaced record/event keys, a session index, and symbol-safe JSON round-trip so sessions, events, and reduced state survive process restarts when a `Host` is built over it.
+- `ProviderStore` cross-process locking — when the adapter exposes `acquire_lock`/`release_lock`, every public operation runs under a TTL-bounded store lock with bounded retry (an exhausted wait budget raises `ConcurrencyError`); adapters without lock methods fall back to an in-process mutex. Stale `expected_sequence` writers still fail with `ConcurrencyError` — locks serialize, they do not merge.
+- `ProviderStore#export` / `ProviderStore#import` — portability parity with `Store`, accepting both all-sessions and single-session shapes with atomic validation before mutating.
+- `Ask::Session::Subscription` — thread-safe subscription with next (Timeout.timeout-backed), wait (alias for next), close, each, and replay.
+- `Ask::Session::InvalidTransitionError` — dedicated error for illegal state transitions (send to closed/aborted, close/abort twice).
+- `Ask::Session::Sink` — ask-runtime event-sink bridge: implements `emit(event_type, event:)` and maps `:tool_started` / `:tool_completed` / `:tool_failed` / `:tool_cancelled` / `:tool_timed_out` to `tool.started` / `tool.completed` / `tool.failed` / `tool.cancelled` / `tool.timed_out` session events via `Host#append`. Duck-typed extraction (no ask-runtime dependency); payloads carry `tool_name`, `tool_call_id`, `input` (started), `outcome`, `duration`, `error`, `output` (terminal), and `turn` when present.
+- `Ask::Session::SessionMismatchError` — dedicated error when a sink receives an event correlated to a different session.
+- `Host#sink(session_id, trace_id:, causation_id:)` — factory that binds a `Sink` to a host and session.
+
+### Changed
+
+- `Host#initialize` now accepts `store:` with a default of `Store.new`.
+- `Host#list` returns `State.reduce` records so close/abort status is reflected.
+- `Host#create` performs store create, event append, and publish atomically under `@mutex`.
+- `Host#publish` prunes closed subscriptions from its per-session list.
+- `Subscription#next` is the primary method using `Queue#pop` wrapped in `Timeout.timeout`; `wait` is aliased to `next` for backward compatibility.
+- `Subscription#close` pushes a sentinel so a blocked `next` wakes with `nil` instead of relying on sleep polling.
+- `Subscription#each` now blocks until close instead of timing out after 0.1s of silence — it yields across quiet periods and only stops when the subscription is closed (restores the documented "yields until closed" contract).
+- `Sink#emit` drops (does not raise) appends to closed or aborted sessions so in-flight tool runs are never failed by the recording boundary; missing sessions still raise `NotFoundError`.

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::Session
+
+Event-sourced session state for the [ask-rb](https://github.com/ask-rb) ecosystem.
+
+## Installation
+
+Requires Ruby 3.2+.
+
+```ruby
+gem "ask-session"
+```
+
+## Overview
+
+Ask::Session provides the foundational value objects and stores for event-sourced session management in ask-rb. It defines immutable records, event envelopes, a concurrency-safe in-memory store, a durable provider-backed store for restart-safe sessions, a replayable host with subscriptions, and a state reducer.
+
+### Core Types
+
+- **`Record`** — immutable snapshot of a session: `id`, `status`, `metadata`, `created_at`, `updated_at`, `version`.
+- **`Event`** — immutable event envelope: `session_id`, `seq`, `type`, `payload`, `trace_id`, `causation_id`, `created_at`.
+
+### Serialization
+
+`Record` and `Event` support portable JSON serialization via `to_h`/`from_h` and the `Codec` module:
+
+```ruby
+# Hash round-trip
+record = Ask::Session::Record.create(id: "s1", status: :active, metadata: { key: "val" })
+hash = record.to_h          # => { id: "s1", status: :active, ..., created_at: <ISO8601>, version: 0 }
+restored = Ask::Session::Record.from_h(hash)
+
+# JSON via Codec
+json = Ask::Session::Codec.dump_record(record)
+record = Ask::Session::Codec.load_record(json)
+
+# Events work the same way
+event = Ask::Session::Event.create(session_id: "s1", seq: 1, type: "session.created")
+json = Ask::Session::Codec.dump_event(event)
+event = Ask::Session::Codec.load_event(json)
+```
+
+Malformed JSON or missing required fields raise `Ask::Session::SerializationError`.
+
+### Store
+
+In-memory event store with optimistic concurrency control:
+
+```ruby
+store = Ask::Session::Store.new
+
+# Create a session
+store.create(id: "sess_001")
+
+# Append events with expected sequence
+event = Ask::Session::Event.new(
+  session_id: "sess_001", seq: 1, type: "session.created",
+  payload: { status: :active }, created_at: Time.now
+)
+store.append_event(event, expected_sequence: 0)
+
+# Load session events
+events = store.events_after("sess_001", after_seq: 0)
+
+# Get all events for a session (frozen)
+events = store.events("sess_001")
+
+# Export/import for portability (all sessions)
+data = store.export
+new_store = Ask::Session::Store.new
+new_store.import(data)
+
+# Export a single session into a fresh store
+single = store.export("sess_001")
+fresh = Ask::Session::Store.new
+fresh.import(single)
+
+# Rebuild session state from events
+record = store.state("sess_001")
+record.status  # => :active
+record.version # => 1
+```
+
+### ProviderStore (durable)
+
+`ProviderStore` is the durable counterpart to `Store`: same API (`create`, `load`, `load!`, `list`, `append_event`, `events`, `events_after`, `current_sequence`, `state`, `export`/`import`), but persisted through any adapter that responds to `get`, `set`, and `delete`. The [ask-state-providers](https://github.com/ask-rb/ask-state-providers) adapters (SQLite, Redis, Postgres, MySQL) work out of the box:
+
+```ruby
+require "ask-state-providers"
+
+adapter = Ask::State::Providers::SQLite.new(path: "sessions.db")
+host = Ask::Session::Host.new(store: Ask::Session::ProviderStore.new(adapter: adapter))
+
+host.create(id: "s1", metadata: { user: "alice" })
+host.send_message("s1", content: "hello")
+host.close("s1", reason: "done")
+adapter.close
+
+# Later — same file, new process:
+adapter = Ask::State::Providers::SQLite.new(path: "sessions.db")
+host = Ask::Session::Host.new(store: Ask::Session::ProviderStore.new(adapter: adapter))
+host.session("s1") # => reduced Record with status: :closed, version: 3
+host.events("s1")  # full history survives the restart
+```
+
+Each session's record and event list persist under namespaced keys (`ask.session:record:*`, `ask.session:events:*`) alongside a session index, using JSON with symbol-safe encoding so statuses and payload symbols round-trip exactly.
+
+When the adapter exposes the provider lock API (`acquire_lock` / `release_lock`), every operation also runs under a cross-process store lock so read-modify-write sequences stay atomic across processes; exhausting the lock wait budget raises `Ask::Session::ConcurrencyError`. Adapters without lock methods fall back to an in-process mutex. Stale `expected_sequence` writers still fail with `ConcurrencyError` — locks serialize, they do not merge.
+
+ask-session keeps zero runtime dependencies: `ProviderStore` duck-types the adapter, so `ask-state-providers` is an optional integration, not a dependency of this gem.
+
+### State Reducer
+
+Rebuild session state from event history:
+
+```ruby
+events = [
+  Ask::Session::Event.new(session_id: "s1", seq: 1, type: "session.created",
+    payload: { status: :active }, created_at: Time.now),
+  Ask::Session::Event.new(session_id: "s1", seq: 2, type: "message.added",
+    payload: { role: :user, content: "hello" }, created_at: Time.now)
+]
+
+record = Ask::Session::State.reduce("s1", events)
+record.status  # => :active
+record.version # => 2
+```
+
+### Host
+
+Replayable session host with publish-subscribe:
+
+```ruby
+store = Ask::Session::Store.new
+host = Ask::Session::Host.new(store: store)
+
+# Create a session
+record = host.create(id: "s1", metadata: { user: "alice" })
+record.status # => :active
+
+# Send messages
+event = host.send_message("s1", content: "hello")
+event.type # => "message.added"
+
+# Query
+host.session("s1")  # => reduced Record
+host.list           # => [Record, ...]
+host.events("s1")   # => [Event, ...]
+
+# Subscribe with replay
+sub = host.subscribe("s1")
+event = sub.next(timeout: 1.0)  # returns event or nil on timeout
+sub.each { |e| puts e.type }    # yields until closed
+sub.close
+
+# Close or abort
+host.close("s1", reason: "done")
+host.abort("s1", reason: "error")
+```
+
+Invalid transitions (send to closed/aborted, close twice) raise `Ask::Session::InvalidTransitionError`.
+
+#### Generic event append
+
+`Host#append` lets adapters record arbitrary event types (tool calls, vendor webhooks, custom lifecycle events) without coupling ask-session to any protocol or agent gem:
+
+```ruby
+# Append a tool event
+event = host.append("s1", type: "tool.started", payload: { tool: "search" })
+
+# Append with trace correlation
+event = host.append("s1",
+  type: "vendor.webhook.received",
+  payload: { raw: body },
+  trace_id: "trace_abc",
+  causation_id: originating_event.trace_id
+)
+```
+
+Every appended event advances the session's reduced `version` and `updated_at`, regardless of event type. Appends to closed or aborted sessions raise `InvalidTransitionError`. Adapters use `append` instead of `send_message` when the event type is not `message.added` — this keeps ask-session free of protocol and agent dependencies.
+
+#### Runtime tool-lifecycle sink
+
+`Ask::Session::Sink` is the boundary to ask-runtime's event-sink contract. Executors in ask-agent, ask-mcp, and ask-sandbox-providers report tool lifecycle through `ExecutionContext#event_sink` by calling `emit(event_type, event:)` — point that sink at a session host and tool history becomes part of the event-sourced session:
+
+```ruby
+host = Ask::Session::Host.new
+host.create(id: "s1")
+
+sink = host.sink("s1", trace_id: "trace_abc")
+# pass `sink` as ExecutionContext's event_sink; runtime emits then record:
+#   :tool_started   -> tool.started
+#   :tool_completed -> tool.completed
+#   :tool_failed    -> tool.failed
+#   :tool_cancelled -> tool.cancelled
+#   :tool_timed_out -> tool.timed_out
+
+host.events("s1").last.payload
+# => { tool_name: "bash", tool_call_id: "tc_1", input: { "cmd" => "ls" }, turn: 3 }
+```
+
+Terminal events carry `outcome` (`:completed`/`:failed`/`:cancelled`/`:timed_out`), `duration` in seconds, `error` when present, and `output` when the runtime result exposes one. The sink duck-types the runtime events' public readers, so ask-session keeps zero runtime dependencies.
+
+Guards: an event correlated to a different session raises `Ask::Session::SessionMismatchError`; appends to closed/aborted sessions are dropped (terminal sessions stop recording without failing an in-flight tool run); missing sessions raise `NotFoundError`; unknown event types are ignored.
+
+```ruby
+sink = Ask::Session::Sink.new(host: host, session_id: "s1", causation_id: originating.trace_id)
+sink.listening?(:tool_started) # => true
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin my-feature`)
+5. Create a Pull Request
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/ask/session/codec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ask
+  module Session
+    module Codec
+      RECORD_KEYS = %i[id status metadata created_at updated_at version].freeze
+      EVENT_KEYS = %i[session_id seq type payload trace_id causation_id created_at].freeze
+
+      def self.dump_record(record)
+        JSON.generate(record.to_h)
+      end
+
+      def self.load_record(json)
+        h = parse_json(json)
+        validate_keys!(h, RECORD_KEYS, "Record")
+        Record.from_h(symbolize(h))
+      rescue JSON::ParserError => e
+        raise SerializationError, "Invalid JSON for Record: #{e.message}"
+      end
+
+      def self.dump_event(event)
+        JSON.generate(event.to_h)
+      end
+
+      def self.load_event(json)
+        h = parse_json(json)
+        validate_keys!(h, EVENT_KEYS, "Event")
+        Event.from_h(symbolize(h))
+      rescue JSON::ParserError => e
+        raise SerializationError, "Invalid JSON for Event: #{e.message}"
+      end
+
+      def self.parse_json(json)
+        raise SerializationError, "Input must be a String" unless json.is_a?(String)
+        JSON.parse(json)
+      end
+      private_class_method :parse_json
+
+      def self.validate_keys!(h, required, label)
+        required.each do |key|
+          ks = key.to_s
+          next if h.key?(ks) && !h[ks].nil?
+
+          raise SerializationError, "Missing required field '#{ks}' in #{label}"
+        end
+      end
+      private_class_method :validate_keys!
+
+      def self.symbolize(h)
+        h.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+      private_class_method :symbolize
+    end
+  end
+end

data/lib/ask/session/event.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Ask
+  module Session
+    Event = Struct.new(:session_id, :seq, :type, :payload, :trace_id, :causation_id, :created_at, keyword_init: true) do
+      def self.create(session_id:, seq:, type:, payload: {}, trace_id: nil, causation_id: nil, created_at: nil)
+        new(
+          session_id: session_id,
+          seq: seq,
+          type: type,
+          payload: payload,
+          trace_id: trace_id || "trace_#{SecureRandom.hex(8)}",
+          causation_id: causation_id,
+          created_at: created_at || Time.now.utc
+        ).freeze
+      end
+
+      def to_h
+        {
+          session_id: session_id,
+          seq: seq,
+          type: type,
+          payload: payload,
+          trace_id: trace_id,
+          causation_id: causation_id,
+          created_at: created_at&.utc&.iso8601
+        }
+      end
+
+      def self.from_h(h)
+        new(
+          session_id: h[:session_id] || h["session_id"],
+          seq: h[:seq] || h["seq"],
+          type: h[:type] || h["type"],
+          payload: deep_symbolize(h[:payload] || h["payload"]),
+          trace_id: h[:trace_id] || h["trace_id"],
+          causation_id: h[:causation_id] || h["causation_id"],
+          created_at: parse_time(h[:created_at] || h["created_at"])
+        )
+      end
+
+      def self.deep_symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+        when Array
+          obj.map { |v| deep_symbolize(v) }
+        else
+          obj
+        end
+      end
+      private_class_method :deep_symbolize
+
+      def self.parse_time(value)
+        case value
+        when Time then value
+        when String then Time.parse(value).utc
+        when nil then nil
+        else
+          raise SerializationError, "Invalid time value: #{value.inspect}"
+        end
+      end
+      private_class_method :parse_time
+
+      def initialize(**)
+        super
+        self.payload = deep_freeze(payload) unless payload.frozen?
+        freeze
+      end
+
+      private
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k] = deep_freeze(v) }.freeze
+        when Array
+          obj.map { |v| deep_freeze(v) }.freeze
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/ask/session/host.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Ask
+  module Session
+    class Host
+      def initialize(store: Store.new)
+        @store = store
+        @subscriptions = {}
+        @mutex = Mutex.new
+        @sub_id_counter = 0
+      end
+
+      def create(id: nil, metadata: {}, status: :active, trace_id: nil)
+        @mutex.synchronize do
+          record = @store.create(id: id, status: status, metadata: metadata)
+          event = Event.create(
+            session_id: record.id,
+            seq: 1,
+            type: "session.created",
+            payload: { session_id: record.id, metadata: metadata, status: status },
+            trace_id: trace_id
+          )
+          @store.append_event(event, expected_sequence: 0)
+          publish(event)
+          State.reduce(record.id, @store.events(record.id))
+        end
+      end
+
+      def session(id)
+        State.reduce(id, @store.events(id))
+      end
+
+      def list
+        @store.list.map { |record| State.reduce(record.id, @store.events(record.id)) }
+      end
+
+      def events(id, after_seq: 0)
+        @store.events_after(id, after_seq: after_seq)
+      end
+
+      def send_message(session_id, content:, trace_id: nil, causation_id: nil)
+        @mutex.synchronize do
+          record = current_state(session_id)
+          assert_open!(record)
+
+          seq = @store.current_sequence(session_id) + 1
+          event = Event.create(
+            session_id: session_id,
+            seq: seq,
+            type: "message.added",
+            payload: { content: content },
+            trace_id: trace_id,
+            causation_id: causation_id
+          )
+          @store.append_event(event, expected_sequence: seq - 1)
+          publish(event)
+          event
+        end
+      end
+
+      def append(session_id, type:, payload: {}, trace_id: nil, causation_id: nil)
+        @mutex.synchronize do
+          record = current_state(session_id)
+          assert_open!(record)
+
+          seq = @store.current_sequence(session_id) + 1
+          event = Event.create(
+            session_id: session_id,
+            seq: seq,
+            type: type,
+            payload: payload,
+            trace_id: trace_id,
+            causation_id: causation_id
+          )
+          @store.append_event(event, expected_sequence: seq - 1)
+          publish(event)
+          event
+        end
+      end
+
+      def close(session_id, reason: nil)
+        @mutex.synchronize do
+          record = current_state(session_id)
+          assert_open!(record)
+
+          seq = @store.current_sequence(session_id) + 1
+          event = Event.create(
+            session_id: session_id,
+            seq: seq,
+            type: "session.ended",
+            payload: { status: :closed, reason: reason }
+          )
+          @store.append_event(event, expected_sequence: seq - 1)
+          publish(event)
+          State.reduce(session_id, @store.events(session_id))
+        end
+      end
+
+      def abort(session_id, reason: nil)
+        @mutex.synchronize do
+          record = current_state(session_id)
+          assert_open!(record)
+
+          seq = @store.current_sequence(session_id) + 1
+          event = Event.create(
+            session_id: session_id,
+            seq: seq,
+            type: "session.aborted",
+            payload: { status: :aborted, reason: reason }
+          )
+          @store.append_event(event, expected_sequence: seq - 1)
+          publish(event)
+          State.reduce(session_id, @store.events(session_id))
+        end
+      end
+
+      def subscribe(session_id, after_seq: 0)
+        @mutex.synchronize do
+          replay = @store.events_after(session_id, after_seq: after_seq)
+          sub_id = next_sub_id
+          sub = Subscription.new(id: sub_id, session_id: session_id)
+          replay.each { |e| sub.enqueue(e) }
+          (@subscriptions[session_id] ||= []) << sub
+          sub
+        end
+      end
+
+      # Build a Sink bound to this host and session — the bridge that
+      # accepts ask-runtime event-sink emissions (tool lifecycle) and
+      # records them as session events.
+      def sink(session_id, trace_id: nil, causation_id: nil)
+        Sink.new(host: self, session_id: session_id, trace_id: trace_id, causation_id: causation_id)
+      end
+
+      private
+
+      def next_sub_id
+        @sub_id_counter += 1
+      end
+
+      def publish(event)
+        subs = @subscriptions[event.session_id]
+        return unless subs
+        subs.reject!(&:closed?)
+        subs.each { |sub| sub.enqueue(event) }
+      end
+
+      def assert_open!(record)
+        case record.status
+        when :closed
+          raise InvalidTransitionError, "Session #{record.id} is closed"
+        when :aborted
+          raise InvalidTransitionError, "Session #{record.id} is aborted"
+        end
+      end
+
+      def current_state(session_id)
+        State.reduce(session_id, @store.events(session_id))
+      end
+    end
+  end
+end