ask-session 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3b79e3300f8b708fcf59dc44f073a75cafb1f1991d9944c8d2fab673cb18a7e
-  data.tar.gz: 5c79377d3098b7ca243198b3bb54ee1e017c69546787562b7e532f21455aa523
+  metadata.gz: 431ac519e177e903d981fd5b8909e0f61d0f3f87701e0da24404b7eff44ba3fc
+  data.tar.gz: 80c72aebcc96b0fd52e183e703732b8f0a804583728c4ffc28f5badb361fdccd
 SHA512:
-  metadata.gz: b87ab80fb5d0f68a613dcc5351d8f632354365673ec46f2b215d43b661be8b06e21fd487b37b9c5f69153aa146868a89072d661cfbfb07032480326ce6e2a78e
-  data.tar.gz: 4fd5f4b12677acb8b3b83c8875f5c8f645959a0133d9dc5b1fb675492f2928bbff685341539e1e277e7a51fa7622e301b6c602514dbd6ebbb1b17bc1c71c738a
+  metadata.gz: 216739303b1cc6ee78a9a6801ae4afcd715dc1c365383b42088870c2c025436106c5c43da4bab23e1c7a19269af658f50962a4fa1f50edfd6aa0f1f1a9b413f8
+  data.tar.gz: 76300dd1e7e90a752a1acad1ba53af2a06655890182a5469daecb2016aa011413a32c395b2209bd6ce8eca4df2843eae5144b170c27c0b03fcb6862580f6393a

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Task guides in `docs/` — in-memory sessions, durable SQLite sessions via the optional ask-state-providers integration, subscriptions and replay, tool lifecycle through `Host#sink`, and export/import — with a `docs/index.md` hub.
+- README restructured to an overview, an in-memory quick start, and links to all guides.
+
+### Changed
+
+- Clarify that `Host#sink` records provider-neutral runtime lifecycle events, while protocol-facing tool events are translated by integration adapters; avoid attaching both producers to the same host for one execution.
+
 ## [0.1.0] - 2026-09-22
 
 ### Added

data/README.md

@@ -2,210 +2,53 @@
 
 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
+Ask::Session provides the foundational value objects and stores for event-sourced
+session management in ask-rb: immutable `Record` and `Event` envelopes, an
+in-memory `Store` with concurrency guardrails, a durable `ProviderStore` for
+restart-safe sessions, a replayable `Host` with subscriptions, a
+`State` reducer, and a `Sink` that records ask-runtime tool lifecycle through
+`Host#sink`. It ships with zero runtime dependencies — durability through
+[ask-state-providers](https://github.com/ask-rb/ask-state-providers) is an
+optional integration.
 
-`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)
-```
+Task guides live in [docs/](https://github.com/ask-rb/ask-session/blob/master/docs/index.md).
 
-Malformed JSON or missing required fields raise `Ask::Session::SerializationError`.
-
-### Store
+## Installation
 
-In-memory event store with optimistic concurrency control:
+Requires Ruby 3.2+.
 
 ```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
+gem "ask-session"
 ```
 
-### ProviderStore (durable)
+## Quick start
 
-`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:
+In-memory, single process:
 
 ```ruby
-require "ask-state-providers"
+require "ask-session"
 
-adapter = Ask::State::Providers::SQLite.new(path: "sessions.db")
-host = Ask::Session::Host.new(store: Ask::Session::ProviderStore.new(adapter: adapter))
+host = Ask::Session::Host.new
 
 host.create(id: "s1", metadata: { user: "alice" })
 host.send_message("s1", content: "hello")
+host.session("s1").version # => 2
 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
+Invalid transitions (sending to a closed session, closing twice) raise
+`Ask::Session::InvalidTransitionError`.
 
-`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:
+## Guides
 
-```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
-```
+- [Guides index](https://github.com/ask-rb/ask-session/blob/master/docs/index.md)
+- [In-memory sessions](https://github.com/ask-rb/ask-session/blob/master/docs/in_memory_sessions.md)
+- [Durable sessions with SQLite (optional ask-state-providers)](https://github.com/ask-rb/ask-session/blob/master/docs/durable_sessions.md)
+- [Subscriptions and replay](https://github.com/ask-rb/ask-session/blob/master/docs/subscriptions_and_replay.md)
+- [Tool lifecycle through Host#sink](https://github.com/ask-rb/ask-session/blob/master/docs/tool_lifecycle.md)
+- [Export and import](https://github.com/ask-rb/ask-session/blob/master/docs/export_import.md)
 
 ## Contributing
 

data/lib/ask/session/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Session
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-session
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Kaka Ruto