ask-agent 0.40.20 → 0.40.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ad845b7f0d67966819af4e0f588f47ff44793e874b56c08dd13208dc3334e5d
-  data.tar.gz: 52c5ef1af2a97cb7cb41a7247c19a614e75ca5138f7192ad71ecde7ffdc3eede
+  metadata.gz: 8119f78526cac8f96b7f6506c1d40e046127dccad46015252e9ea0805e15c677
+  data.tar.gz: be381f8d8fbb4b104ba79ab0a1cece93918c8ef028bfdb4fc24dd6ae49399726
 SHA512:
-  metadata.gz: '078e71e0cf4fd80c5d08badd68377eb4b73cf0923f46dc6f065bab94d3106323892bb307acf717ea3640907939e5706645b42986c5d1fc003544801e2fece9e0'
-  data.tar.gz: '068595e1f29705bcda12462c342b49a4a5a2d055c5f5f75c5c24edbe02bd8475a8803e6f7ecebb0fddd782dac84e168db8f877d6fe6e2eda566d2bb000e15f26'
+  metadata.gz: aee841408cd187f95b2d54f6bbb0820fac09865bf58f1af38680b1847088a8aca7c1a187008e93a98a6cf39941fd65e0690dd78a16b6d07491c6d0ec0573bcf2
+  data.tar.gz: c6b6c736800ae14baa95355f692294da8f428af180c404852a5aa9141905d5bfb776994f59aab21e772f3263e40c3c542b32009cee779f1263ade62c8d095cb5

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+## [Unreleased]
+
+
+## [0.40.21] — 2026-09-22
+
+### Added
+
+- **`Ask::Agent::SessionAdapter` — bridges an agent session to
+  `Ask::Session::Host`.** Records user input and per-run snapshots as
+  event-sourced ask-session events, maps agent events (turn, streaming,
+  tool, todo, plan, error) onto session event types with `trace_id` /
+  `causation_id` propagation, and resumes from the latest snapshot
+  (`SessionAdapter.resume`). Resume survives process restarts when the host
+  store is durable (e.g. `Ask::Session::ProviderStore` over
+  `ask-state-providers`). Requires the new runtime dependency
+  `ask-session >= 0.1.0` (the single session store; no second store added).
+  Resume validates the snapshot before restoring, so a malformed snapshot
+  raises `SessionAdapter::Error` instead of leaving the agent half-restored.
+
+### Fixed
+
+- **`Session#turn_count` is now maintained during runs.** The counter was
+  only ever reset at run start (or restored from a checkpoint), never
+  incremented — so `SessionEnd`, audit-log entries, persisted
+  `metadata.turn_count`, and `SessionAdapter` snapshots all recorded `0` for
+  live runs. Turns are now counted on `TurnStart`, matching the loop's own
+  count (`reset: true` scopes it to the run; `reset: false` accumulates).
+
+
+## [0.40.20] — 2026-09-21
+
+### Changed
+
+- **Agent tool execution unified with ask-runtime.** `ToolExecutor` runs
+  tool calls through the runtime's execution contract, exposing the current
+  runtime call and execution context (`Ask.current_runtime_call` /
+  `Ask.current_runtime_context`) while a tool executes, and conforming to
+  the runtime executor contract.
+- Requires `ask-runtime >= 0.1.0`.
+
+
+## [0.40.19] — 2026-09-20
+
+### Added
+
+- **Bundled `agent.build_agents` skill** — teaches building agents with
+  ask-rb (definitions, sessions, tools, configuration, common patterns).
+  Auto-discovered via `Gem.find_files` when ask-skills is present.
+- **`askr skills install` / `askr skills uninstall`** with
+  `--global|--local|--dir`, plus auto-sync of managed skill copies on
+  every CLI invocation.
+
+
+## [0.40.18] — 2026-09-19
+
+### Changed
+
+- **`Agent.new` and `Session.new` unified.** The shared implementation
+  lives in `Session.build_from_definition`; `Agent.new` delegates to it,
+  `Session.new` supports definition lookup, and `Ask.chat` accepts `name:`
+  for definition lookup. The duplicate `build_session_from_definition` and
+  `resolve_definition_tools` helpers were removed from the `Agent` module.
+
+
 ## [0.40.17] — 2026-09-18
 
 ### Added

data/README.md

@@ -102,6 +102,35 @@ under multiple OpenAI-compatible providers). A `provider:` passed to
 `Session.new` or declared in an agent `Definition` always wins over the global
 default.
 
+## Durable sessions (ask-session)
+
+`Ask::Agent::SessionAdapter` bridges a session to an event-sourced
+`Ask::Session::Host`. Every run records the user input, the mapped agent
+events, and an `agent.snapshot`; `SessionAdapter.resume` restores the latest
+snapshot — including after a process restart, as long as the host store is
+durable (for example `Ask::Session::ProviderStore` over
+`ask-state-providers`' SQLite adapter).
+
+```ruby
+require "ask-agent"
+require "ask/session"
+
+host = Ask::Session::Host.new(store: Ask::Session::Store.new)
+
+session = Ask::Agent::Session.new(model: "gpt-4o", id: "chat-1")
+adapter = Ask::Agent::SessionAdapter.create(agent: session, host: host)
+adapter.run("Hello")
+
+# Later (even in a new process, with the same durable store):
+resumed = Ask::Agent::Session.new(model: "gpt-4o", id: "chat-1")
+adapter = Ask::Agent::SessionAdapter.resume(agent: resumed, host: host, session_id: "chat-1")
+adapter.run("Continue where we left off")
+```
+
+`SessionAdapter::Error` is raised when the session record or its latest
+snapshot cannot be found. This requires the `ask-session` gem (a runtime
+dependency of ask-agent).
+
 ## Full documentation
 
 The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.

data/lib/ask/agent/session.rb

@@ -107,7 +107,10 @@ module Ask
         @turn_id = 0
         @queued_steers = []
         @steer_mutex = Mutex.new
-        on(Events::TurnStart) { @turn_id += 1 }
+        on(Events::TurnStart) do
+          @turn_id += 1
+          @turn_count += 1
+        end
         @created_at = Time.now
         @_no_tools_instructed = false
 

data/lib/ask/agent/session_adapter.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ask/session"
+
+module Ask
+  module Agent
+    # Adapter that bridges an Ask::Agent::Session to an Ask::Session::Host.
+    #
+    # Maps agent events to event-sourced ask-session events, persists a
+    # snapshot at the end of each run, and supports resume from the latest
+    # durable snapshot.
+    #
+    #   adapter = SessionAdapter.create(agent: session, host: host)
+    #   result = adapter.run("Hello")
+    #
+    #   restored = SessionAdapter.resume(agent: session, host: host, session_id: id)
+    #   restored.run("Follow up")
+    #
+    class SessionAdapter
+      SNAPSHOT_TYPE = "agent.snapshot"
+
+      # Raised when resume cannot find the ask-session record or its
+      # latest snapshot.
+      class Error < Ask::Agent::Error; end
+
+      attr_reader :agent, :host, :session_id
+
+      def initialize(agent:, host:, session_id: agent.id, metadata: {}, create: false)
+        @agent = agent
+        @host = host
+        @session_id = session_id
+        @current_trace_id = nil
+        @current_turn_id = nil
+        @current_causation_id = nil
+
+        @host.create(id: @session_id, metadata: metadata) if create
+
+        attach_event_handler
+      end
+
+      # Create a new ask-session record and return the adapter.
+      #
+      # @param agent [Ask::Agent::Session] the agent session
+      # @param host [Ask::Session::Host] the session host
+      # @param metadata [Hash] session metadata
+      # @return [SessionAdapter]
+      def self.create(agent:, host:, metadata: {})
+        record = host.create(id: agent.id, metadata: metadata)
+        new(agent: agent, host: host, session_id: record.id, metadata: metadata, create: false)
+      end
+
+      # Attach to an existing ask-session and restore the latest snapshot.
+      #
+      # Contract: Ask::Session::Host#session raises
+      # Ask::Session::NotFoundError for a missing record (it never returns
+      # nil); both missing-session and missing-snapshot failures surface as
+      # SessionAdapter::Error.
+      #
+      # @param agent [Ask::Agent::Session] the agent session (will be populated from snapshot)
+      # @param host [Ask::Session::Host] the session host
+      # @param session_id [String] the ask-session record id
+      # @return [SessionAdapter]
+      # @raise [SessionAdapter::Error] if the session or snapshot is not found
+      def self.resume(agent:, host:, session_id:)
+        begin
+          host.session(session_id)
+        rescue Ask::Session::NotFoundError
+          raise Error, "Session not found: #{session_id.inspect}"
+        end
+
+        events = host.events(session_id)
+        snapshot_event = events.reverse_each.find { |e| e.type == SNAPSHOT_TYPE }
+        raise Error, "No snapshot found for session #{session_id.inspect}" unless snapshot_event
+
+        payload = snapshot_event.payload
+        messages = payload[:messages] || payload["messages"] || []
+
+        # Validate before mutating the agent so a malformed snapshot cannot
+        # leave it half-restored.
+        messages.each do |msg|
+          role = msg.is_a?(Hash) ? (msg[:role] || msg["role"]) : nil
+          raise Error, "Snapshot for session #{session_id.inspect} contains a message without a role" unless role
+        end
+
+        agent.instance_variable_set(:@turn_count, payload[:turn_count] || payload["turn_count"] || 0)
+        agent.chat.reset_messages!
+        messages.each do |msg|
+          agent.chat.add_message(
+            role: (msg[:role] || msg["role"]).to_sym,
+            content: deserialize_content(msg[:content] || msg["content"]),
+            tool_call_id: msg[:tool_call_id] || msg["tool_call_id"],
+            tool_calls: msg[:tool_calls] || msg["tool_calls"]
+          )
+        end
+        agent.instance_variable_set(:@messages, agent.chat.messages.dup)
+
+        new(agent: agent, host: host, session_id: session_id, create: false)
+      end
+
+      # Current trace id for the running trace.
+      # @return [String, nil]
+      def current_trace_id
+        @current_trace_id
+      end
+
+      # Current turn identifier (stable per TurnStart).
+      # @return [Integer, nil]
+      def current_turn_id
+        @current_turn_id
+      end
+
+      # Run the agent and record events in the ask-session.
+      #
+      # @param message [String] the user message
+      # @param trace_id [String, nil] optional trace id (auto-generated if nil)
+      # @param causation_id [String, nil] optional causation id linking to the
+      #   event that caused this run
+      # @param options [Hash] forwarded to agent.run
+      # @return [String] the agent response
+      def run(message, trace_id: nil, causation_id: nil, **options)
+        @current_trace_id = trace_id || "trace_#{SecureRandom.hex(8)}"
+        @current_causation_id = causation_id
+
+        # Record user input as a message event.
+        input_event = @host.send_message(
+          @session_id,
+          content: message.to_s,
+          trace_id: @current_trace_id,
+          causation_id: @current_causation_id
+        )
+        @current_causation_id ||= input_event.trace_id
+
+        begin
+          result = @agent.run(message, **options)
+
+          # Append snapshot for resume.
+          snapshot = build_snapshot
+          @host.append(
+            @session_id,
+            type: SNAPSHOT_TYPE,
+            payload: snapshot,
+            trace_id: @current_trace_id,
+            causation_id: @current_causation_id
+          )
+
+          result
+        rescue Ask::Agent::Aborted
+          @host.append(
+            @session_id,
+            type: "turn.aborted",
+            payload: { turn_id: @current_turn_id },
+            trace_id: @current_trace_id,
+            causation_id: @current_causation_id
+          )
+          raise
+        rescue => e
+          @host.append(
+            @session_id,
+            type: "turn.failed",
+            payload: { error: e.message, error_class: e.class.name },
+            trace_id: @current_trace_id,
+            causation_id: @current_causation_id
+          )
+          raise
+        ensure
+          @current_turn_id = nil
+          @current_causation_id = nil
+        end
+      end
+
+      # Request agent abort without writing a terminal session event.
+      def abort
+        @agent.abort
+      end
+
+      # Close the ask-session (terminal: :closed).
+      def close
+        @host.close(@session_id)
+      end
+
+      # Abort the ask-session (terminal: :aborted).
+      def abort_session
+        @host.abort(@session_id)
+      end
+
+      private
+
+      def attach_event_handler
+        @agent.on_event do |event|
+          handle_event(event)
+        end
+      end
+
+      def handle_event(event)
+        trace_id = @current_trace_id
+        causation_id = @current_causation_id
+        turn_id = @current_turn_id
+
+        case event
+        when Events::TurnStart
+          @current_turn_id = (@current_turn_id || 0) + 1
+          turn_id = @current_turn_id
+          @host.append(@session_id, type: "turn.started", payload: { turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::TextDelta
+          @host.append(@session_id, type: "model.streaming", payload: { content: event.content, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ThinkingDelta
+          @host.append(@session_id, type: "model.thinking", payload: { content: event.content, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ToolExecutionStart
+          @host.append(@session_id, type: "tool.use", payload: { tool_name: event.name, arguments: event.arguments, tool_call_id: event.id, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ToolExecutionUpdate
+          @host.append(@session_id, type: "tool.delta", payload: { tool_name: event.name, tool_call_id: event.id, partial_result: event.partial_result, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ToolExecutionEnd
+          @host.append(@session_id, type: "tool.result", payload: { tool_name: event.name, tool_call_id: event.id, result: event.result, is_error: event.is_error, duration_ms: event.duration_ms, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::TodoUpdated
+          @host.append(@session_id, type: "todos.updated", payload: { todos: event.todos }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::PlanProposed
+          @host.append(@session_id, type: "plan.proposed", payload: { plan: event.plan }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::PlanApproved
+          @host.append(@session_id, type: "plan.approved", payload: { plan: event.plan }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::PlanRejected
+          @host.append(@session_id, type: "plan.rejected", payload: { plan: event.plan }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::Error
+          @host.append(@session_id, type: "error", payload: { message: event.error, recoverable: event.recoverable }, trace_id: trace_id, causation_id: causation_id)
+        end
+      end
+
+      def build_snapshot
+        {
+          messages: (@agent.messages || []).map(&:to_h),
+          turn_count: @agent.turn_count || 0
+        }
+      end
+
+      def self.deserialize_content(content)
+        content.is_a?(Array) ? content.map { |block| Ask::Content.from_h(block) } : content
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.40.20"
+    VERSION = "0.40.21"
   end
 end

data/lib/ask/agent.rb

@@ -216,6 +216,7 @@ require_relative "agent/chat"
 require_relative "agent/telemetry"
 require_relative "agent/tool_abort_controller"
 require_relative "agent/session"
+require_relative "agent/session_adapter"
 require_relative "agent/loop"
 require_relative "agent/reflector"
 require_relative "agent/evaluator"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.40.20
+  version: 0.40.21
 platform: ruby
 authors:
 - Kaka Ruto
@@ -121,6 +121,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.9'
+- !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: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -216,6 +230,7 @@ files:
 - lib/ask/agent/reflector.rb
 - lib/ask/agent/scheduler.rb
 - lib/ask/agent/session.rb
+- lib/ask/agent/session_adapter.rb
 - lib/ask/agent/stream_transforms/base.rb
 - lib/ask/agent/stream_transforms/extract_json.rb
 - lib/ask/agent/stream_transforms/pipeline.rb