ask-agent 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb1a00c9b6f32029b7d27271482fe82dfa7333601776537a38160635bf4fde0b
-  data.tar.gz: 80d666d9485e6e058c9a81d20fdbfa48b4b196a33d1675655fbbd7f6ffea9240
+  metadata.gz: c80f27cbdec5b3808533dba4861762e19e4ef81c084be099a4a7eb0b2169170e
+  data.tar.gz: 34e5388035a8f216df468039bf8c7e304296d7661832e8109df4d76fbb527193
 SHA512:
-  metadata.gz: d7ef76f83baba0df18a1f60a6a00aae8cefb0b191ccf6eb0d5b680ed68e0c305dde891591673805b28bec5705ae632da2bd6acc4bd5810602a3b04878483f890
-  data.tar.gz: 639f577894d439805d0f06d988c4b528241f82b31656dea7b9a28ba54eca173c4262e3a48b865705bfb0ae153653c9a9c4e4ac6fc3cd7cb8fe02c92efe4495f9
+  metadata.gz: bb1bf1b6aac7a61a650291f9dcabd781c0a664cb09d97c7f2cc2fcdcfaa035b71adef2c423ebacfaae0de04d0524b4dff649f503921006837e0644d9a9f86615
+  data.tar.gz: d718885adebbaf33f2b9a2b95704968494d14e3080746a58da37c9518af475ac09103357014e5bea98339d56150ce63a162c6ac9a9c8ae4cffa07f13716b8793

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [0.14.0] — 2026-07-23
+
+### Added
+
+- **`state:` keyword on Session** — Accepts any `Ask::State::Adapter` directly. Sessions persist conversation state, tool results, and metadata. Replaces `persistence:` keyword (still supported for backward compatibility).
+- **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.
+- **`Ask::State::Adapter#clear`** — Abstract method added to the adapter contract. Memory adapter implements it.
+
+### Changed
+
+- **Session behind the scenes now uses `@state.set`/`@state.get`/`@state.delete`** instead of the old `@persistence.save`/`@persistence.load`/`@persistence.delete`. Custom adapters must respond to `set`/`get`/`delete`.
+
+## [0.13.0] — 2026-07-23
+
+### Added
+
+- **ModelFallback middleware** — Switches to a fallback model+provider when the primary LLM call fails with a rate limit, server error, or service unavailable. Supports static and dynamic (lambda-based) fallback lists. Credentials resolve automatically via `Ask::Auth`.
+  - Static fallbacks: ordered list of `{ model:, provider: }` hashes
+  - Dynamic fallbacks: lambda receiving `(error, request)` returning the list
+  - Custom eligible errors: configure which errors trigger fallback
+  - Each fallback builds its own provider instance with resolved credentials
+
+### Changed
+
+- `Pipeline::KNOWN_MIDDLEWARES` now includes `:model_fallback`.
+
 ## [0.12.0] — 2026-07-22
 
 ### Added

data/README.md

@@ -60,13 +60,13 @@ end
 
 Opt-in safety modules:
 
-- **PermissionGate** — Require approval for destructive tools (write, edit, bash, destroy)
+- **Permissions** — Access control for tools. Supports named access modes (`:full_access`, `:read_only`, `:ask_before_changes`) or custom blocked-tool lists.
 - **RateLimiter** — Prevent runaway tool calls (configurable per-minute and per-turn limits)
 - **AuditLog** — Immutable, append-only log of every tool call
 
 ```ruby
 extensions = [
-  Ask::Agent::Extensions::PermissionGate.new,
+  Ask::Agent::Extensions::Permissions.new(mode: :read_only),
   Ask::Agent::Extensions::RateLimiter.new(max_calls_per_minute: 30),
   Ask::Agent::Extensions::AuditLog.new(path: "agent.log")
 ]
@@ -81,6 +81,57 @@ session = Ask::Agent::Session.new(
 )
 ```
 
+## Middleware
+
+Wrapping LLM provider calls with cross-cutting behavior:
+
+- **RetryOnFailure** — Retry on rate limits and server errors with exponential backoff
+- **ModelFallback** — Switch to a fallback model+provider on transient errors
+- **LogCalls** — Log every LLM provider call
+- **DefaultSettings** — Inject default generation parameters
+
+```ruby
+Ask::Agent.configure do |c|
+  c.middleware.use :retry_on_failure, max_retries: 3
+  c.middleware.use :model_fallback, fallbacks: [
+    { model: "claude-sonnet-4",  provider: :anthropic },
+    { model: "gemini-2.0-flash", provider: :google }
+  ]
+  c.middleware.use :log_calls, logger: Rails.logger
+  c.middleware.use :default_settings, temperature: 0.7
+end
+```
+
+### ModelFallback
+
+When the primary LLM is overloaded or down, `ModelFallback` transparently switches to a backup model+provider. Credentials for each provider are resolved automatically.
+
+**Static fallbacks** — ordered list tried in sequence:
+```ruby
+c.middleware.use :model_fallback, fallbacks: [
+  { model: "claude-sonnet-4",  provider: :anthropic },
+  { model: "gemini-2.0-flash", provider: :google }
+]
+```
+
+**Dynamic fallbacks** — lambda that receives the error and request:
+```ruby
+c.middleware.use :model_fallback, fallbacks: ->(error, request) {
+  if request[:messages].sum { |m| m[:content].to_s.length } > 100_000
+    [{ model: "claude-sonnet-4", provider: :anthropic }]  # long-context
+  else
+    [{ model: "gpt-4o-mini", provider: :openai }]           # cheaper
+  end
+}
+```
+
+**Custom eligible errors** — by default rate limits, server errors, and service unavailable:
+```ruby
+c.middleware.use :model_fallback,
+  fallbacks: [{ model: "claude-sonnet-4", provider: :anthropic }],
+  eligible_errors: [Ask::RateLimitError, Ask::ServerError]
+```
+
 ## Configuration
 
 ```ruby

data/lib/ask/agent/extensions/permission_gate.rb

@@ -1,70 +1,13 @@
 # frozen_string_literal: true
 
+# Legacy alias — PermissionGate has been renamed to Permissions.
+# This file will be removed in the next major version.
+require_relative "permissions"
+
 module Ask
   module Agent
     module Extensions
-      class PermissionGate
-        DEFAULT_TOOLS = %i[write edit bash destroy].freeze
-
-        def initialize(blocked_tools: DEFAULT_TOOLS, timeout: nil)
-          @blocked_tools = Array(blocked_tools).map(&:to_sym)
-          @timeout = timeout
-          @pending = {}
-          @mutex = Mutex.new
-        end
-
-        def before_tool_call(tool_call, _context)
-          return { action: :proceed } unless @blocked_tools.include?(tool_call.name.to_sym)
-
-          if approved?(tool_call)
-            { action: :proceed }
-          else
-            request_approval(tool_call)
-          end
-        end
-
-        def approve(tool_call_id)
-          @mutex.synchronize do
-            entry = @pending[tool_call_id]
-            return false unless entry
-            entry[:approved] = true
-          end
-        end
-
-        def pending_approvals
-          @mutex.synchronize { @pending.values.reject { |e| e[:approved] } }
-        end
-
-        private
-
-        def approved?(tool_call)
-          @mutex.synchronize do
-            key = tool_call.id
-            entry = @pending[key]
-            return false unless entry
-
-            if @timeout && (Time.now - entry[:created_at]) > @timeout
-              @pending.delete(key)
-              return false
-            end
-
-            entry[:approved]
-          end
-        end
-
-        def request_approval(tool_call)
-          @mutex.synchronize do
-            @pending[tool_call.id] = {
-              tool_call: tool_call,
-              approved: false,
-              created_at: Time.now
-            }
-          end
-
-          warn "[PermissionGate] Tool '#{tool_call.name}' requires approval. Call approve('#{tool_call.id}') to allow."
-          { action: :block, reason: "Tool '#{tool_call.name}' requires approval" }
-        end
-      end
+      PermissionGate = Permissions
     end
   end
 end

data/lib/ask/agent/extensions/permissions.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Extensions
+      class Permissions
+        DEFAULT_TOOLS = %i[write edit bash destroy].freeze
+
+        ACCESS_MODES = {
+          full_access:       { blocked_tools: [] }.freeze,
+          ask_before_changes: { blocked_tools: DEFAULT_TOOLS }.freeze,
+          read_only:         { blocked_tools: %i[write edit bash destroy] }.freeze
+        }.freeze
+
+        def initialize(mode: nil, blocked_tools: nil, timeout: nil)
+          @mode = mode
+          @timeout = timeout
+          @pending = {}
+          @mutex = Mutex.new
+
+          @blocked_tools = if mode
+            config = ACCESS_MODES[mode]
+            raise ArgumentError, "Unknown access mode: #{mode.inspect}. Valid: #{ACCESS_MODES.keys.join(', ')}" unless config
+            config[:blocked_tools].dup
+          elsif blocked_tools
+            Array(blocked_tools).map(&:to_sym)
+          else
+            DEFAULT_TOOLS.dup
+          end
+        end
+
+        def before_tool_call(tool_call, _context)
+          return { action: :proceed } unless @blocked_tools.include?(tool_call.name.to_sym)
+
+          if approved?(tool_call)
+            { action: :proceed }
+          else
+            request_approval(tool_call)
+          end
+        end
+
+        def approve(tool_call_id)
+          @mutex.synchronize do
+            entry = @pending[tool_call_id]
+            return false unless entry
+            entry[:approved] = true
+          end
+        end
+
+        def pending_approvals
+          @mutex.synchronize { @pending.values.reject { |e| e[:approved] } }
+        end
+
+        private
+
+        def approved?(tool_call)
+          @mutex.synchronize do
+            key = tool_call.id
+            entry = @pending[key]
+            return false unless entry
+
+            if @timeout && (Time.now - entry[:created_at]) > @timeout
+              @pending.delete(key)
+              return false
+            end
+
+            entry[:approved]
+          end
+        end
+
+        def request_approval(tool_call)
+          @mutex.synchronize do
+            @pending[tool_call.id] = {
+              tool_call: tool_call,
+              approved: false,
+              created_at: Time.now
+            }
+          end
+
+          warn "[Permissions] Tool '#{tool_call.name}' requires approval. Call approve('#{tool_call.id}') to allow."
+          { action: :block, reason: "Tool '#{tool_call.name}' requires approval" }
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/loop.rb

@@ -17,7 +17,7 @@ module Ask
       @max_consecutive_tool_turns = max_consecutive_tool_turns
       end
 
-      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil)
+      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil)
         raise MaxTurnsExceeded if @turn_count >= @max_turns
 
         event_emitter.emit(Events::TurnStart.new)
@@ -103,6 +103,9 @@ module Ask
           compactor.run(event_emitter: event_emitter)
         end
 
+        # Persist after each turn so mid-session crashes don't lose progress
+        persist&.call
+
         raise MaxTurnsExceeded if @turn_count >= @max_turns
 
         # Recursive call — LLM processes tool results
@@ -114,7 +117,8 @@ module Ask
           compactor: compactor,
           hooks: hooks,
           event_emitter: event_emitter,
-          session_id: session_id
+          session_id: session_id,
+          persist: persist
         )
       end
 

data/lib/ask/agent/middleware/model_fallback.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Middleware
+      # Switches to a fallback model+provider when the primary LLM call fails
+      # with a transient error (rate limit, server error, service unavailable).
+      #
+      # Each fallback specifies both a model and a provider slug, so the
+      # middleware can switch from e.g. OpenAI to Anthropic transparently.
+      # Credentials for each provider are resolved automatically via
+      # {Ask::Auth.resolve}.
+      #
+      # @example Basic usage — fallback to Anthropic when OpenAI is overloaded
+      #   pipeline.use :model_fallback, fallbacks: [
+      #     { model: "claude-sonnet-4",     provider: :anthropic },
+      #     { model: "gemini-2.0-flash",    provider: :google }
+      #   ]
+      #
+      # @example With failure-trigger customization
+      #   pipeline.use :model_fallback, fallbacks: [
+      #     { model: "claude-sonnet-4", provider: :anthropic, on_error: [Ask::RateLimitError, Ask::ServerError] }
+      #   ]
+      #
+      # @example Using the block form to choose fallbacks dynamically
+      #   pipeline.use :model_fallback, fallbacks: ->(error, request) {
+      #     if request[:messages].sum { |m| m[:content].to_s.length } > 100_000
+      #       [{ model: "claude-sonnet-4", provider: :anthropic }]  # use long-context model
+      #     else
+      #       [{ model: "gpt-4o-mini", provider: :openai }]          # use cheaper model
+      #     end
+      #   }
+      class ModelFallback < Base
+        DEFAULT_ELIGIBLE_ERRORS = [
+          Ask::RateLimitError, Ask::ServerError, Ask::ServiceUnavailable
+        ].freeze
+
+        def initialize(fallbacks:, eligible_errors: nil)
+          @fallbacks = fallbacks.respond_to?(:call) ? fallbacks : Array(fallbacks)
+          @eligible_errors = Array(eligible_errors || DEFAULT_ELIGIBLE_ERRORS)
+          raise ArgumentError, "At least one fallback is required" if Array(@fallbacks).empty?
+        end
+
+        def around_request(provider, request)
+          # Try primary provider
+          begin
+            return yield
+          rescue *@eligible_errors => e
+            result = try_fallbacks(request, error: e)
+            return result if result
+            raise
+          end
+        end
+
+        private
+
+        def try_fallbacks(request, error:)
+          fallback_list = resolve_fallback_list(error, request)
+
+          fallback_list.each do |fb|
+            begin
+              new_provider = build_fallback_provider(fb[:provider])
+              request[:model] = fb[:model]
+              return invoke_fallback(new_provider, request)
+            rescue *@eligible_errors
+              next  # Try next fallback
+            end
+          end
+
+          nil  # All fallbacks exhausted
+        end
+
+        def resolve_fallback_list(error, request)
+          list = if @fallbacks.respond_to?(:call)
+            @fallbacks.call(error, request)
+          else
+            @fallbacks
+          end
+          raise "Fallback list must be an array of hashes, got #{list.class}" unless list.is_a?(Array)
+          list
+        end
+
+        def build_fallback_provider(provider_slug)
+          slug = provider_slug.to_s
+          klass = Ask::Provider.resolve(slug)
+          klass.new(fallback_config(slug))
+        end
+
+        def invoke_fallback(provider, request)
+          provider.chat(
+            request[:messages],
+            model: request[:model],
+            tools: request[:tools],
+            temperature: request[:temperature],
+            stream: request[:stream],
+            schema: request[:schema],
+            **request[:extra_params]
+          )
+        end
+
+        def fallback_config(slug)
+          key = Ask::Auth.resolve(:"#{slug}_api_key") rescue nil
+          config = { api_key: key }
+          config[:"#{slug}_api_key"] = key
+          Ask::LLM::Config.new(config)
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/middleware/pipeline.rb

@@ -19,7 +19,8 @@ module Ask
         KNOWN_MIDDLEWARES = {
           retry_on_failure: "Ask::Agent::Middleware::RetryOnFailure",
           log_calls: "Ask::Agent::Middleware::LogCalls",
-          default_settings: "Ask::Agent::Middleware::DefaultSettings"
+          default_settings: "Ask::Agent::Middleware::DefaultSettings",
+          model_fallback: "Ask::Agent::Middleware::ModelFallback"
         }.freeze
 
         def initialize

data/lib/ask/agent/session.rb

@@ -18,7 +18,7 @@ module Ask
       attr_reader :skills_registry
 
       def initialize(model:, tools: [], max_turns: 25, max_tool_retries: 3,
-                     compactor: nil, hooks: {}, persistence: nil,
+                     compactor: nil, hooks: {}, state: nil, persistence: nil,
                      id: nil, system_prompt: nil, parallel_tools: true,
                      reflector: nil, telemetry: true, meta_agent: nil,
                      agent_dir: nil, **chat_options)
@@ -48,11 +48,10 @@ module Ask
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
 
-        # Build system context from typed sources
         @system_context = build_system_context(system_prompt)
         apply_system_context
 
-        @persistence = persistence
+        @state = state || persistence
 
         reflector_opts = reflector.is_a?(Hash) ? reflector : {}
         @reflector = if reflector
@@ -79,8 +78,7 @@ module Ask
 
         emit(Events::SessionStart.new)
 
-        active_tools = resolve_tools(tools || [])
-        active_tools = @tools if active_tools.empty?
+        active_tools = @tools
 
         if active_tools.empty? && !@_no_tools_instructed
           @chat.add_message(role: :system, content: "You have no tools available. Do not claim you can look up information or use tools of any kind. Just respond based on your existing knowledge.")
@@ -90,16 +88,17 @@ module Ask
         begin
           @tool_executor.telemetry = @telemetry
 
-          response = @loop.run_turn(
-            chat: @chat,
-            message: message,
-            tools: active_tools,
-            tool_executor: @tool_executor,
-            compactor: @compactor,
-            hooks: @hooks,
-            event_emitter: self,
-            session_id: @id
-          )
+	          response = @loop.run_turn(
+	            chat: @chat,
+	            message: message,
+	            tools: active_tools,
+	            tool_executor: @tool_executor,
+	            compactor: @compactor,
+	            hooks: @hooks,
+	            event_emitter: self,
+	            session_id: @id,
+	            persist: @state ? method(:persist!) : nil
+	          )
 
           @total_input_tokens += @loop.last_input_tokens.to_i
           @total_output_tokens += @loop.last_output_tokens.to_i
@@ -123,7 +122,7 @@ module Ask
           raise
         ensure
           @running = false
-          persist! if @persistence
+          persist! if @state
         end
 
         @tool_calls_made = @tool_executor.total_executions
@@ -194,34 +193,37 @@ module Ask
       def deleted? = @deleted
 
       def save
-        persist! if @persistence
+        persist! if @state
       end
 
       def self.load(id, adapter:)
-        data = adapter.load(id)
+        data = adapter.get(id)
         return nil unless data
 
+        data = deep_symbolize_keys(data)
+
         session = new(
           id: data[:id],
           model: data.dig(:metadata, :model),
           tools: data.dig(:metadata, :tools)&.map(&:constantize) || [],
-          persistence: adapter
+          state: adapter
         )
 
-        data[:messages].each do |msg|
-          session.chat.add_message(
-            role: msg[:role].to_sym,
-            content: msg[:content],
-            tool_call_id: msg[:tool_call_id]
-          )
-        end
-
-        session
+	        data[:messages].each do |msg|
+	          session.chat.add_message(
+	            role: msg[:role].to_sym,
+	            content: msg[:content],
+	            tool_call_id: msg[:tool_call_id]
+	          )
+	        end
+	
+	        session.instance_variable_set(:@messages, session.chat.messages.dup)
+	        session
       end
 
       def delete
         @deleted = true
-        @persistence&.delete(@id)
+        @state&.delete(@id)
       end
 
       def abort
@@ -291,7 +293,7 @@ module Ask
       end
 
       def persist!
-        @persistence.save(@id, {
+        @state.set(@id, {
           id: @id,
           messages: @chat.messages.map { |m|
             {
@@ -359,6 +361,19 @@ module Ask
         SystemContext.new(sources)
       end
 
+      # Recursively convert string keys to symbol keys in hashes.
+      # Needed when loading session data that was serialized through JSON.
+      def self.deep_symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize_keys(v) }
+        when Array
+          obj.map { |e| deep_symbolize_keys(e) }
+        else
+          obj
+        end
+      end
+
       # Render the system context and apply it to the chat.
       def apply_system_context
         rendered = @system_context.render

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.12.0"
+    VERSION = "0.14.0"
   end
 end

data/lib/ask/agent.rb

@@ -21,6 +21,7 @@ module Ask
     class UnknownAgent < Error; end
 
     module Extensions
+      autoload :Permissions, "ask/agent/extensions/permissions"
       autoload :PermissionGate, "ask/agent/extensions/permission_gate"
       autoload :RateLimiter, "ask/agent/extensions/rate_limiter"
       autoload :AuditLog, "ask/agent/extensions/audit_log"
@@ -32,6 +33,7 @@ module Ask
       autoload :RetryOnFailure, "ask/agent/middleware/retry_on_failure"
       autoload :LogCalls, "ask/agent/middleware/log_calls"
       autoload :DefaultSettings, "ask/agent/middleware/default_settings"
+      autoload :ModelFallback, "ask/agent/middleware/model_fallback"
     end
 
     module StreamTransforms

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -160,6 +160,7 @@ files:
 - lib/ask/agent/events.rb
 - lib/ask/agent/extensions/audit_log.rb
 - lib/ask/agent/extensions/permission_gate.rb
+- lib/ask/agent/extensions/permissions.rb
 - lib/ask/agent/extensions/rate_limiter.rb
 - lib/ask/agent/hooks.rb
 - lib/ask/agent/loop.rb
@@ -167,6 +168,7 @@ files:
 - lib/ask/agent/middleware/base.rb
 - lib/ask/agent/middleware/default_settings.rb
 - lib/ask/agent/middleware/log_calls.rb
+- lib/ask/agent/middleware/model_fallback.rb
 - lib/ask/agent/middleware/pipeline.rb
 - lib/ask/agent/middleware/retry_on_failure.rb
 - lib/ask/agent/persistence/base.rb