ask-app-server 0.4.20 → 0.4.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8da88a56836df0e35058cf843c44e1ea6c487879ae3a2e60d972bdc1dd2df688
-  data.tar.gz: 19952aeaece5d94114c2f761a39dd89e2a362eda6e35321f402b0425a5747fc3
+  metadata.gz: a798da52caa5bd806b1b44c6ffc698f3f8c6eda35b46c8106a47ca5858c3dc96
+  data.tar.gz: 8dfaa77e96b1b3e181010cfa691b347ef04f1ff77ae4f8975e769f9d269e3a90
 SHA512:
-  metadata.gz: 5a319040bb32da4ca8ea567b84539f6544ea3ea99b7bb4281ad4b1314375d9106904f2d8d44f248c47a8d3a2aa3f44bfb4401ad970f59b96d63cff1672b6a352
-  data.tar.gz: 5a497e8d9f889312763a57b7ce313677dd0548013ed8bb2a6e58c03ca76c8dfd16c0bd24550ed4cf6610999564f6b7dccbae6acc34089f62c86031c59f3c4669
+  metadata.gz: ec63de1fa030729903f69f0cabfb975a7aa8046fa73edf86a6161ff2cf7b2bae4ec07a59a1547c1278150c62196af7c7a2b914c9d12d79ceb1f93145831f1e1d
+  data.tar.gz: ee5bf7058adf48edf457e6689155a4f5f23d6b6450373bd7c08faa73deee9e98619f56ecb4417e76a364a43850c17d00c6488f677f488c7eaf70d324fbf6f85c

data/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## [Unreleased]
+
+### Fixed
+
+- **Durable session listings survive restart.** When `state_adapter:` is
+  configured, the app-server session registry now uses the same persistent
+  adapter as the ask-session Host, so SQLite and PostgreSQL sessions remain
+  discoverable through `session/list` after restart. Reattaching a durable
+  session no longer reports it as a duplicate live session.
+
+## [0.4.21] - 2026-09-22
+
+### Added
+
+- **Durable ask-session integration — `Ask::Session::Host` is the event
+  source of truth for replay.** `SessionManager` owns one Host
+  (injectable via `SessionManager.new(host:)`, default in-process);
+  every session creates its ask-session record at create time, each
+  canonical protocol event is appended to it at the `EventTranslator`
+  boundary, and `session/events`, subscribe snapshots, and cursor push
+  all read back from the Host — replay no longer depends on the
+  in-memory translator buffer (events survive the buffer cap). Session
+  close closes the durable record (`Host#close`); the wire seq is the
+  Host seq, contiguous from 1. Requires the new runtime dependency
+  `ask-session >= 0.1.0` (the single session store; no second store
+  added). Protocol translation is unchanged and stays in app-server;
+  the JSON-RPC surface, approvals, plans, subscriptions, and
+  `ask-session-protocol` wire behavior are untouched.
+- **Durable restart resume.** `SessionManager.new(state_adapter:)` and
+  `AgentAdapter.new(state_adapter:)` accept any ask-state-providers
+  adapter; it is wrapped in `Ask::Session::ProviderStore` and handed to
+  the Host, so records, events, and snapshots survive restarts. No
+  adapter means the default in-memory Host — nothing changes for
+  callers that do not opt in, and no concrete backend is forced.
+- **`session/resume` now falls back to the durable Host.** When the live
+  registry does not know the session, the manager rebuilds a fresh
+  compatible `Ask::Agent::Session` under the same id (configured from
+  the manager's defaults — model/tools/prompt are not serialized), and
+  when the Host holds an `agent.snapshot` restores the conversation
+  through `Ask::Agent::SessionAdapter.resume`. In-process resume (the
+  live adapter) still wins and is unchanged; a terminal (closed)
+  durable record refuses resume with the existing `SessionNotFound`
+  (-32004) error. The restored SessionAdapter's own event handler is
+  detached after restore — the `EventTranslator` remains the single
+  protocol writer, so the wire vocabulary never double-writes.
+- **Successful runs append an `agent.snapshot`** (messages +
+  turn_count — the payload `SessionAdapter.resume` expects) to the
+  Host after a clean turn; failed/aborted turns write none. The
+  snapshot is Host-internal and stays off the wire.
+
+### Fixed
+
+- **Failure events always wake watchers.** Model stream drops, run
+  failures, and disconnects now reliably emit `turn.failed` with turn
+  identity: `EventTranslator#turn_failed` always carries a `turnId`
+  (the active turn's, or a fresh one when the run died before
+  `turn.started`) — previously a run that failed without an announced
+  turn raised a protocol validation error inside the run thread, the
+  event was swallowed, and every watcher waited forever on a ghost
+  turn. The adapter settles `running` before emitting, so observers
+  woken by `turn.failed` (the herdr pane reporter, session observers)
+  see the run as finished rather than a ghost "working" that no later
+  event corrects, and emission itself is guarded so a translation
+  error can never take down the run thread after the fact. Aborted
+  turns remain client-requested, not failures.
+- **A disconnected watcher cannot starve the others.** `push_pending`
+  isolates delivery per connection: a socket that dies mid-write
+  (EPIPE/ECONNRESET) no longer aborts the whole pass — the remaining
+  subscribed connections still receive their events (including the
+  terminal `turn.failed`), and the dead connection's cursor holds
+  until its reader reaps it.
+- **Durable replay over `ProviderStore`** no longer drops events:
+  rehydrated Host events carry symbolized payload keys, which failed
+  protocol payload validation and were silently dropped from
+  `session/events` — the adapter now normalizes payload keys to the
+  string-keyed wire shape at the boundary.
+
+### Boundaries (unchanged this slice)
+
+- **`Ask::Agent::SessionAdapter` is not attached.** Its `run` lacks the
+  steer/queue/staleness semantics `session/send` depends on, and its
+  event vocabulary (`message.added`, `agent.snapshot`, no
+  `turn.completed`/approval events, non-wire payloads) would double-write
+  and diverge from the canonical contract. The app-server keeps driving
+  runs itself and appends protocol events to the Host directly; its
+  lifecycle surface maps 1:1 (`SessionAdapter#create`/`#close` ≡
+  `Host#create`/`Host#close`).
+- **`Host#send_message` is unused:** the protocol has no `message.added`
+  event; user input enters through `session/send`.
+- **`Host#subscribe` is unused:** delivery stays per-connection cursor
+  polling over `Host#events` (any number of clients per session).
+- **`session/resume` prefers the live adapter** (in-process, unchanged);
+  only when the registry lacks the session does it fall back to the
+  durable Host snapshot described above.
+- **`SessionStore`'s state-backed event helpers** were never on the wire
+  path and are not the replay source; the Host is.
+
 ## [0.4.17] - 2026-09-18
 
 ### Changed

data/README.md

@@ -111,6 +111,11 @@ Every event is a canonical `{type, seq, payload}` envelope, delivered as a
 The full vocabulary, payload shapes, method specs, and versioning live in
 the ask-session-protocol gem (JSON Schema artifact included).
 
+The event log itself is event-sourced in [ask-session](https://github.com/ask-rb/ask-session)'s
+`Host`: replay (`session/events`, subscribe snapshots, cursor push) reads
+the durable log rather than an in-memory buffer, and protocol translation
+stays at the app-server boundary.
+
 ## Clients
 
 Any client that speaks the app-server protocol can connect — including

data/lib/ask/app_server/agent_adapter.rb

@@ -10,7 +10,24 @@ module Ask
     # owns the approval queue wiring (approval events surface as
     # approval.required / approval.updated) and the interaction controls
     # (approve/reject by id, plan approve/reject) that any client can call.
+    #
+    # The durable ask-session layer: every session has an
+    # Ask::Session::Host record, and each canonical event is appended to
+    # it at this boundary (protocol translation stays here — the Host is
+    # an event-sourced log, it knows nothing about the wire vocabulary).
+    # Replay and cursor delivery read the Host, so the durable log is the
+    # source of truth; the translator's in-memory buffer serves live
+    # observers only. A successful run also appends an agent.snapshot
+    # (the ask-agent restart-resume payload); restart resume rebuilds a
+    # fresh session through Ask::Agent::SessionAdapter.resume when the
+    # Host holds one ({#resume_from_host}).
     class AgentAdapter
+      # Event types the ask-session Host writes itself (Host#create /
+      # Host#close). The adapter must not re-append them: the read path
+      # maps the Host's lifecycle payloads back to the wire shape, which
+      # keeps Host seq and wire seq contiguous from 1.
+      HOST_OWNED_EVENT_TYPES = %w[session.created session.ended].freeze
+
       # The underlying ask-agent session.
       attr_reader :session
 
@@ -20,6 +37,9 @@ module Ask
       # The session ID (same as ask-agent session id).
       attr_reader :session_id
 
+      # The durable ask-session host this session's records live in.
+      attr_reader :host
+
       # Whether a turn is currently in progress.
       attr_reader :running
 
@@ -33,10 +53,18 @@ module Ask
       # @param approval [Symbol] :off, :require, or :auto
       # @param require_approval [Array<String>, nil] tool names gated behind
       #   human approval when approval is :require
+      # @param host [Ask::Session::Host, nil] durable session/event host;
+      #   defaults to a private in-process Host
+      # @param state_adapter [Object, nil] ask-state-providers adapter
+      #   (get/set/delete) used to construct a ProviderStore-backed Host
+      #   when no +host+ is given; ignored when +host+ is provided
+      # @param created_at [Time, nil] session creation time (restart
+      #   resume passes the durable record's timestamp)
       # @param session_opts [Hash] remaining options passed to
       #   Ask::Agent::Session.new (hooks, plan_mode, todos, ...)
       def initialize(model:, tools: nil, system_prompt: nil, agent_dir: nil,
-                     approval: :off, require_approval: nil, **session_opts)
+                     approval: :off, require_approval: nil, host: nil,
+                     state_adapter: nil, created_at: nil, **session_opts)
         @model = model
         @system_prompt = system_prompt
         @tools = resolve_tools(tools)
@@ -44,6 +72,8 @@ module Ask
         @approval = approval
         @require_approval = require_approval
         @agent_dir = agent_dir
+        @host = host || build_durable_host(state_adapter)
+        @durable_record = false
         # The session's workspace is the tools' home: bash commands
         # without an explicit cd run there (default_workdir), so the
         # agent never drifts into the host's cwd — the recurring
@@ -57,7 +87,7 @@ module Ask
         @running_mutex = Mutex.new
         @run_thread = nil
         @abort_requested = false
-        @created_at = Time.now
+        @created_at = created_at || Time.now
         @logger = Logger.new($stdout, level: ENV["DEBUG"] ? Logger::DEBUG : Logger::WARN)
       end
 
@@ -68,6 +98,8 @@ module Ask
         @translator.on_event = @on_event_block if @on_event_block
         @session = build_session
         @session_id = @session.id
+        create_durable_record
+        @translator.on_append = method(:persist_event)
         @session.on_event { |event| handle_agent_event(event) }
         @translator.session_created(@session_id)
         @session_id
@@ -79,10 +111,30 @@ module Ask
         @session_id = session.id
         @translator = EventTranslator.new
         @translator.on_event = @on_event_block if @on_event_block
+        # Attach to the durable record when the Host already knows this
+        # session (full history stays replayable); otherwise this adapter
+        # runs translator-buffer-only, as before.
+        @durable_record = durable_record?
+        @translator.on_append = method(:persist_event) if @durable_record
         @session.on_event { |event| handle_agent_event(event) }
         @session_id
       end
 
+      # Rebuild this adapter around a durable session the Host already
+      # records (restart resume): a fresh compatible ask-agent session
+      # under the same id, restored from the latest agent.snapshot when
+      # one exists, then attached through the regular {#resume} path.
+      #
+      # Model/tools/prompt configuration is intentionally not
+      # deserialized — the caller configures this adapter with its own
+      # defaults before calling.
+      def resume_from_host(session_id)
+        @session = build_session(id: session_id)
+        @session_id = session_id
+        restore_from_snapshot
+        resume(@session)
+      end
+
       # Register an observer for every canonical event this session emits
       # (translations plus approval/plan/session-lifecycle emissions).
       # May be called before start_session; the block is applied when the
@@ -209,10 +261,12 @@ module Ask
 
       # ── Lifecycle ───────────────────────────────────────────────────────
 
-      # Close the session: delete its state and emit session.ended.
+      # Close the session: delete its state, emit session.ended, and
+      # close the durable ask-session record.
       def close!
         @session&.delete if @session.respond_to?(:delete)
         @translator&.session_ended(@session_id, reason: "closed")
+        close_durable_record
         true
       end
 
@@ -237,18 +291,161 @@ module Ask
       end
 
       # Events after a given sequence number.
+      #
+      # The durable ask-session log is the source of truth: replay and
+      # cursor delivery read Host#events and re-validate each record as a
+      # canonical protocol event at this boundary. Falls back to the
+      # in-memory translator buffer only when this adapter has no durable
+      # record (resume() attached to a session the Host does not know).
       def events_after(after_seq)
-        pending_events.select { |e| e.seq > after_seq }
+        after = after_seq.to_i
+        return pending_events.select { |e| e.seq > after } unless @durable_record
+
+        @host.events(@session_id, after_seq: after).filter_map { |record| wire_event(record) }
+      rescue Ask::Session::NotFoundError
+        pending_events.select { |e| e.seq > after }
       end
 
       private
 
-      def build_session
+      # Build the durable Host from an injectable state adapter (any
+      # ask-state-providers get/set/delete backend, wrapped in
+      # ProviderStore). No adapter means the default in-process Host —
+      # durability is opt-in and no concrete backend is forced.
+      def build_durable_host(state_adapter)
+        return Ask::Session::Host.new unless state_adapter
+
+        Ask::Session::Host.new(store: Ask::Session::ProviderStore.new(adapter: state_adapter))
+      end
+
+      # Restore the conversation from the durable snapshot through
+      # Ask::Agent::SessionAdapter.resume. That adapter registers its
+      # own durable event handler as it attaches, which would append
+      # ask-agent-shaped events alongside this adapter's protocol events
+      # (double-writing the log with a second, non-wire vocabulary) —
+      # restoration is done at that point, so the handler it just added
+      # is popped off and the EventTranslator stays the single protocol
+      # writer.
+      def restore_from_snapshot
+        return false unless durable_snapshot?
+
+        Ask::Agent::SessionAdapter.resume(agent: @session, host: @host, session_id: @session_id)
+        handlers = @session.instance_variable_get(:@event_handlers)
+        handlers[:all].pop if handlers
+        true
+      rescue Ask::Agent::SessionAdapter::Error => e
+        @logger.debug("Snapshot restore skipped for #{@session_id}: #{e.message}")
+        false
+      end
+
+      # Whether the durable Host holds a restart-resume snapshot for
+      # this session.
+      def durable_snapshot?
+        return false unless @host && @session_id
+
+        @host.events(@session_id).any? { |e| e.type == Ask::Agent::SessionAdapter::SNAPSHOT_TYPE }
+      rescue Ask::Session::NotFoundError
+        false
+      end
+
+      # Create the durable ask-session record. The Host's own
+      # session.created event is the session's first durable event; the
+      # translator's session.created (identical wire shape, seq 1) is
+      # served from it via #wire_event instead of being re-appended.
+      def create_durable_record
+        @host.create(id: @session_id, metadata: { model: @model })
+        @durable_record = true
+      end
+
+      # Whether the Host already holds a record for this session.
+      def durable_record?
+        return false unless @host && @session_id
+
+        @host.session(@session_id)
+        true
+      rescue Ask::Session::NotFoundError
+        false
+      end
+
+      # Append a canonical protocol event to the durable Host. The Host is
+      # a dumb log: protocol vocabulary enters and leaves at this
+      # boundary. Host-owned lifecycle events are skipped (see
+      # HOST_OWNED_EVENT_TYPES). Failures never break live delivery — a
+      # close racing a run just stops receiving durable appends.
+      def persist_event(event)
+        return unless @durable_record
+        return if HOST_OWNED_EVENT_TYPES.include?(event.type)
+
+        @host.append(@session_id, type: event.type, payload: event.payload)
+      rescue StandardError => e
+        @logger.debug("Durable append failed for #{event.type}: #{e.message}")
+      end
+
+      # Close the durable record (Host writes session.ended itself).
+      # Already-closed/aborted records are fine to ignore.
+      def close_durable_record
+        return unless @durable_record
+
+        @host.close(@session_id, reason: "closed")
+      rescue Ask::Session::Error
+        nil
+      end
+
+      # Append the end-of-run snapshot the restart-resume path restores
+      # through Ask::Agent::SessionAdapter.resume (same payload shape:
+      # messages + turn_count). Written only after a clean run — an
+      # aborted or failed turn leaves no half-restorable state. The Host
+      # keeps it; wire_event filters it out of protocol replay (it is
+      # not a protocol vocabulary type). Failures never break the live
+      # turn.
+      def persist_snapshot
+        return unless @durable_record
+        return unless @session.respond_to?(:chat) && @session.respond_to?(:turn_count)
+
+        @host.append(
+          @session_id,
+          type: Ask::Agent::SessionAdapter::SNAPSHOT_TYPE,
+          payload: {
+            messages: @session.chat.messages.map(&:to_h),
+            turn_count: @session.turn_count || 0
+          }
+        )
+      rescue StandardError => e
+        @logger.debug("Durable snapshot failed for #{@session_id}: #{e.message}")
+      end
+
+      # Rebuild a durable Host record as a canonical wire event.
+      # Returns nil for records outside the protocol vocabulary (e.g.
+      # ask-session-internal types), which never reach clients.
+      def wire_event(record)
+        return nil unless Ask::SessionProtocol::Events.known?(record.type)
+
+        payload =
+          case record.type
+          when "session.created"
+            { "sessionId" => record.session_id }
+          when "session.ended"
+            reason = record.payload[:reason] || record.payload["reason"] || "closed"
+            { "sessionId" => record.session_id, "reason" => reason.to_s }
+          else
+            # Host Event rehydration (and the durable ProviderStore JSON
+            # round-trip) symbolizes payload keys; the wire contract is
+            # string-keyed. Normalize here, at the protocol boundary.
+            record.payload.transform_keys(&:to_s)
+          end
+        Ask::SessionProtocol::Events.event(type: record.type, seq: record.seq, payload: payload)
+      rescue ArgumentError => e
+        @logger.debug("Skipping non-wire durable event #{record.type}: #{e.message}")
+        nil
+      end
+
+      def build_session(id: nil)
         opts = @session_opts.dup
         hooks = opts.delete(:hooks) || {}
         approval_option = build_approval_option
         opts[:approval] = approval_option if approval_option
         opts[:plan_mode] = false unless opts.key?(:plan_mode)
+        opts[:id] = id if id
 
         Ask::Agent::Session.new(
           model: @model,
@@ -291,6 +488,7 @@ module Ask
         end
 
         @run_thread = Thread.new do
+          failure = nil
           begin
             @session.run(content, reset: false)
             # Drain steers queued while the turn was running (mid-execution
@@ -303,23 +501,36 @@ module Ask
             # mid-turn (a dead connection, a provider that closed the
             # stream early). Without this, the client would wait on a
             # ghost run forever. Surface it as a failure so the fix
-            # loop can redeliver.
+            # loop can redeliver. No snapshot in that case: the turn's
+            # conversation state is incomplete.
             if @translator.turn_active?
               @logger.error("Turn ended without a completion event — the model stream dropped mid-turn")
-              @translator.turn_failed("The model stream ended without completing the turn (the connection dropped mid-stream)")
+              failure = "The model stream ended without completing the turn (the connection dropped mid-stream)"
+            else
+              persist_snapshot
             end
           rescue => e
             # An aborted turn raises Ask::Agent::Aborted — that's not a
-            # failure, the client asked for it. Everything else is a real
-            # run failure the client must see: without a turn.failed, a
-            # watching board would wait forever on a dead turn. The
+            # failure, the client asked for it. Everything else is a
+            # run failure the client must see — a raised run, or a
+            # disconnect from the model (EOF, ECONNRESET, a closed
+            # socket) surfaced as an exception: without a turn.failed,
+            # a watching board would wait forever on a dead turn. The
             # translator's failure event carries the message.
             unless e.is_a?(Ask::Agent::Aborted) || e.class.name.to_s.include?("Aborted")
               @logger.error("Agent run failed: #{e.class}: #{e.message}")
-              @translator.turn_failed(e.message.to_s[0, 500])
+              message = e.message.to_s
+              message = e.class.name if message.strip.empty?
+              failure = message[0, 500]
             end
           ensure
+            # Settle the run before the terminal event goes out: a
+            # watcher woken by turn.failed (an observer, the pane
+            # reporter) must see the run as finished, not a ghost
+            # "working" it will never see corrected — no state event
+            # fires after this point.
             @running_mutex.synchronize { @running = false }
+            emit_failure(failure) if failure
             @logger.debug("Run thread ended: turn_active=#{@translator.turn_active?} last_seq=#{@translator.last_seq}")
           end
         end
@@ -327,6 +538,17 @@ module Ask
         true
       end
 
+      # Wake the watchers: translate the run's terminal failure into a
+      # turn.failed event. Never raises — if emission itself failed, a
+      # raised error here would kill the run thread after the fact and
+      # leave the turn marked active with no terminal event, hanging
+      # every watcher this method exists to wake.
+      def emit_failure(message)
+        @translator.turn_failed(message)
+      rescue StandardError => e
+        @logger.error("Failed to emit turn.failed: #{e.class}: #{e.message}")
+      end
+
       def handle_agent_event(event)
         @translator.translate(event)
       end

data/lib/ask/app_server/event_translator.rb

@@ -31,6 +31,13 @@ module Ask
       # side effects (e.g. the pane reporter) hook here.
       attr_accessor :on_event
 
+      # Optional observer called with every emitted canonical Event after
+      # buffering — the persistence hook the adapter uses to append the
+      # event to the durable ask-session Host. Separate from +on_event+
+      # (a single slot) so live observers and durable appends never
+      # clobber each other.
+      attr_accessor :on_append
+
       def initialize
         @events = []
         @seq = 0
@@ -151,12 +158,20 @@ module Ask
       end
 
       # Emit a turn.failed event. Called by the adapter when a run dies
-      # (an exception, or a stream that ended without completing).
+      # (an exception, a disconnect, or a stream that ended without
+      # completing).
+      #
+      # The protocol requires turnId, so the payload always carries
+      # identity: the active turn's id when the turn announced itself,
+      # a fresh one when the run died before TurnStart (or after the
+      # previous turn ended — that id is spent and must not be reused).
+      # Emitting without one would raise at the protocol boundary, the
+      # event would never reach the buffer, and every watcher of the
+      # dead run would wait forever.
       def turn_failed(message)
+        @turn_id = SecureRandom.uuid unless @turn_active && @turn_id
         @turn_active = false
-        payload = { "error" => message.to_s }
-        payload["turnId"] = @turn_id if @turn_id
-        emit("turn.failed", payload)
+        emit("turn.failed", { "error" => message.to_s, "turnId" => @turn_id })
       end
 
       private
@@ -260,6 +275,7 @@ module Ask
         @events << event
         @events.shift if @events.size > MAX_EVENTS
         on_event&.call(event)
+        on_append&.call(event)
         [event]
       end
     end

data/lib/ask/app_server/server.rb

@@ -193,23 +193,32 @@ module Ask
       # several sessions, and the client routes events to the right
       # watcher — without it, a multi-session client would record one
       # session's events into another's run.
+      #
+      # Delivery is isolated per connection: a watcher whose socket died
+      # mid-write (EPIPE/ECONNRESET) must not abort the pass and starve
+      # the remaining watchers of their terminal events. The failed
+      # connection's cursor does not advance, so undelivered events
+      # redeliver on the next pass (clients dedup by seq); its reader
+      # thread reaps the dead connection on EOF.
       def push_pending
         connections.each do |connection|
           connection.subscriptions.keys.each do |session_id|
-            adapter = @session_manager.get(session_id)
-            next unless adapter
-
-            events = adapter.events_after(connection.cursor(session_id))
-            next if events.empty?
-
-            events.each do |ev|
-              connection.write({ method: "session/event", params: { sessionId: session_id, event: ev.to_h } })
+            begin
+              adapter = @session_manager.get(session_id)
+              next unless adapter
+
+              events = adapter.events_after(connection.cursor(session_id))
+              next if events.empty?
+
+              events.each do |ev|
+                connection.write({ method: "session/event", params: { sessionId: session_id, event: ev.to_h } })
+              end
+              connection.advance(session_id, events.last.seq)
+            rescue => e
+              @logger.debug("Push error: #{e.message}") if ENV["DEBUG"]
             end
-            connection.advance(session_id, events.last.seq)
           end
         end
-      rescue => e
-        @logger.debug("Push error: #{e.message}") if ENV["DEBUG"]
       end
 
       # ── Response/notification helpers ──────────────────────────────────
@@ -347,13 +356,15 @@ module Ask
           { sessions: sessions }
         end
 
-        # Session: resume
+        # Session: resume — the live adapter when this process holds it,
+        # otherwise a durable restart resume: rebuild a fresh agent
+        # session from the Host (restored from its snapshot when one
+        # exists) and attach it to the live registry.
         handler("session/resume") do |params, _id|
           session_id = params["sessionId"] || params[:sessionId]
           raise InvalidRequest, "sessionId is required" unless session_id
 
-          adapter = @session_manager.get(session_id)
-          raise Ask::AppServer::SessionNotFound, "Session #{session_id} not found" unless adapter
+          adapter = @session_manager.resume_session(session_id)
 
           {
             sessionId: session_id,

data/lib/ask/app_server/session_manager.rb

@@ -8,6 +8,14 @@ module Ask
     # Orchestrates creation, resumption, subscription, messaging, aborting,
     # interaction resolution (approvals, plan), closing, and event polling
     # across AgentAdapter instances stored in SessionStore.
+    #
+    # Owns the durable ask-session layer: one Ask::Session::Host shared by
+    # every session (injectable via +host+, or built from an injectable
+    # +state_adapter+ via ProviderStore), which is the event source of
+    # truth for replay. SessionStore keeps live adapter registry and
+    # subscription state only. Resume prefers the live adapter; when the
+    # live registry does not know the session it rebuilds one from the
+    # durable Host ({#resume_session}).
     class SessionManager
       # Default tools if none specified.
       DEFAULT_TOOLS = %w[bash read write edit glob grep].freeze
@@ -19,12 +27,14 @@ module Ask
       DEFAULT_REQUIRE_APPROVAL = %w[write edit bash destroy].freeze
 
       attr_reader :store
+      attr_reader :host
       attr_reader :permission_mode
       attr_reader :blocked_tools
       attr_reader :permission_timeout
 
-      def initialize(store: nil, permission_mode: :on_request, blocked_tools: nil, permission_timeout: 300)
-        @store = store || SessionStore.new
+      def initialize(store: nil, host: nil, state_adapter: nil, permission_mode: :on_request, blocked_tools: nil, permission_timeout: 300)
+        @store = store || SessionStore.new(state: state_adapter)
+        @host = host || build_host(state_adapter)
         @permission_mode = permission_mode
         @blocked_tools = (blocked_tools || DEFAULT_REQUIRE_APPROVAL).map(&:to_s)
         @permission_timeout = permission_timeout
@@ -60,8 +70,6 @@ module Ask
       def create_session(workspace_path: nil, mode: nil, model: nil, tools: nil, system_prompt: nil)
         approval_opts, plan_mode = resolve_approval(mode)
 
-        # Extract provider prefix from model string (e.g., "opencode_go/deepseek-v4-flash")
-        model_id, model_provider = parse_model_string(model || DEFAULT_MODEL)
         # A provider-qualified model must stay resolvable: the agent's
         # model catalog looks up bare ids, so the prefixed model is
         # registered under its provider before the session builds its
@@ -69,8 +77,7 @@ module Ask
         # bare "deepseek-v4-flash" which the catalog may not know — the
         # session falls back to the wrong provider and the run hangs
         # silently on a missing credential.
-        register_prefixed_model(model_id, model_provider) if model_provider
-        model_for_agent = model_provider ? model_id : (model || DEFAULT_MODEL)
+        model_for_agent = resolve_agent_model(model)
 
         adapter = AgentAdapter.new(
           model: model_for_agent,
@@ -79,7 +86,8 @@ module Ask
           agent_dir: workspace_path,
           approval: approval_opts[:mode],
           require_approval: approval_opts[:require_approval],
-          plan_mode: plan_mode
+          plan_mode: plan_mode,
+          host: @host
         )
 
         session_id = adapter.start_session
@@ -97,6 +105,49 @@ module Ask
         session_id
       end
 
+      # Resume a session: the live adapter when this process still holds
+      # it (in-process resume, unchanged), otherwise rebuild it from the
+      # durable ask-session Host — a fresh compatible agent session under
+      # the same id, restored from its agent.snapshot through
+      # Ask::Agent::SessionAdapter.resume when the Host holds one.
+      #
+      # Model/tool/prompt configuration is not deserialized across
+      # restarts: the rebuilt adapter uses this manager's configured
+      # defaults.
+      #
+      # @return [AgentAdapter]
+      # @raise [SessionNotFound] when neither the live registry nor the
+      #   durable Host knows the session, or its durable record is
+      #   terminal (closed/aborted)
+      def resume_session(session_id)
+        adapter = @store.get(session_id)
+        return adapter if adapter
+
+        record = durable_record(session_id)
+        raise Ask::AppServer::SessionNotFound, "Session #{session_id} not found" unless record
+        unless record.status == :active
+          raise Ask::AppServer::SessionNotFound, "Session #{session_id} is not active"
+        end
+
+        approval_opts, plan_mode = resolve_approval(nil)
+        adapter = AgentAdapter.new(
+          model: resolve_agent_model(nil),
+          tools: DEFAULT_TOOLS,
+          system_prompt: build_default_system_prompt(nil),
+          approval: approval_opts[:mode],
+          require_approval: approval_opts[:require_approval],
+          plan_mode: plan_mode,
+          host: @host,
+          created_at: record.created_at
+        )
+        adapter.resume_from_host(session_id)
+        @store.add(session_id, adapter)
+
+        adapter.on_event { |event| notify_session_event(adapter.session_id, event) }
+        @logger.info("Resumed session #{session_id} from the durable host")
+        adapter
+      end
+
       # Remove a session.
       def destroy_session(session_id)
         adapter = @store.get(session_id)
@@ -271,6 +322,33 @@ module Ask
 
       private
 
+      # Build the durable Host. With an injectable state adapter (any
+      # ask-state-providers get/set/delete backend) the Host is backed
+      # by ProviderStore, so records, events, and snapshots survive
+      # restarts; without one the default in-memory Host is unchanged.
+      def build_host(state_adapter)
+        return Ask::Session::Host.new unless state_adapter
+
+        Ask::Session::Host.new(store: Ask::Session::ProviderStore.new(adapter: state_adapter))
+      end
+
+      # The durable ask-session record, or nil when the Host does not
+      # know the session.
+      def durable_record(session_id)
+        @host.session(session_id)
+      rescue Ask::Session::NotFoundError
+        nil
+      end
+
+      # Resolve the configured model for a new agent session: parse an
+      # optional provider prefix and register it in the catalog so the
+      # bare id stays resolvable (see create_session).
+      def resolve_agent_model(model)
+        model_id, model_provider = parse_model_string(model || DEFAULT_MODEL)
+        register_prefixed_model(model_id, model_provider) if model_provider
+        model_provider ? model_id : (model || DEFAULT_MODEL)
+      end
+
       # Resolve the session mode into approval options + plan mode.
       #
       # @return [Array(Hash, Boolean)] [{ mode:, require_approval: }, plan_mode]

data/lib/ask/app_server/session_store.rb

@@ -40,10 +40,12 @@ module Ask
 
         @mutex.synchronize do
           existing = @state.get("#{SESSION_PREFIX}#{session_id}")
-          raise Ask::AppServer::SessionAlreadyExists, "Session #{session_id} already exists" if existing
+          if existing && @adapters.key?(session_id)
+            raise Ask::AppServer::SessionAlreadyExists, "Session #{session_id} already exists"
+          end
 
           @state.set("#{SESSION_PREFIX}#{session_id}", metadata)
-          @state.list_append(SESSION_LIST_KEY, session_id, max_length: 200)
+          @state.list_append(SESSION_LIST_KEY, session_id, max_length: 200) unless existing
           @adapters[session_id] = adapter
         end
       end
@@ -75,7 +77,7 @@ module Ask
           metadata = @state.get("#{SESSION_PREFIX}#{sid}")
           if metadata
             adapter = @adapters[sid]
-            metadata.merge(
+            metadata.transform_keys(&:to_sym).merge(
               running: adapter&.running || false,
               idle: adapter&.idle? || true
             )

data/lib/ask/app_server/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module AppServer
-    VERSION = "0.4.20"
+    VERSION = "0.4.22"
   end
 end

data/lib/ask-app-server.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ask/agent"
+require "ask-session"
 require "ask-session-protocol"
 require "ask-tools-shell"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-app-server
 version: !ruby/object:Gem::Version
-  version: 0.4.20
+  version: 0.4.22
 platform: ruby
 authors:
 - Kaka Ruto
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.19
+        version: 0.40.22
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.19
+        version: 0.40.22
 - !ruby/object:Gem::Dependency
   name: ask-core
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: ask-session
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: ask-session-protocol
   requirement: !ruby/object:Gem::Requirement