ask-agent 0.20.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44a7d741bb255935ebfa4790a7da3d36dc4b4200ab8ebd1e061f8d31b194c798
-  data.tar.gz: ad33f40cffc85328e4cc753291db6fa5730fd7edffc52fcf4f96b34eade7a863
+  metadata.gz: cf7561a6eebc134d4e84ba829e637638a783eb7dd425c1b1c24d2d879e5ff47e
+  data.tar.gz: 73cdf03eec1b27f3e50cbfa28399bdf17994ea1b5925be36ce463ebf48c6669d
 SHA512:
-  metadata.gz: 3e8c63b1465e8090d050e92b03773ec1a38caf9b2c4b22abbb08f5b19007e50317d5befa058343ea6c08e11450ad0a5c5c2f99609ef64d5f00ef9855893f5086
-  data.tar.gz: 02e39e5fdb5ecdcd91dc57572a0594d90155534ed7dc282b1029a4041fe7943b94e45c5066e1c86c75b1cb0efb7824a5eb522dcd650c81ad41cfd5177dfafc98
+  metadata.gz: 37b261bba11ac89e4051b2f631305ed6741ae8ba6a18f0973a2fa7a04416d3dd84d2ca9e4517d01f4776a21fbf143125a51bcceb74b67ce361d9c4ea35e15279
+  data.tar.gz: bc3051e56b9b68a003da46e1ee4c4ec10265239bfc2482c6cc335caf510f099256e1487526ead9277687004a0bb4c68926efb9f51db338b103f69188f21ed60a

data/CHANGELOG.md

@@ -1,3 +1,81 @@
+## [0.23.0] — 2026-07-30
+
+### Added
+
+- **`Ask::Agent::Configuration#default_provider` — global default provider**.
+  Pins which provider serves the default model when the model id is
+  registered under multiple providers (e.g. the same model on several
+  OpenAI-compatible endpoints). `Chat#build_provider` falls back to the
+  global default before the model's own catalog entry. A per-chat
+  `provider:` override or a Definition-level `provider` always wins.
+
+## [0.22.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Agent::Extensions::AuditLog` — event-driven audit logging with pluggable adapters**.
+  Subscribes to all session events and writes them to a configurable adapter.
+  Ships with two built-in adapters:
+
+  - **`FileAdapter`** — appends JSON lines to a file (development/quick-start)
+  - **`ActiveRecordWriter`** — writes to an `ask_audit_logs` table, auto-creates it
+    on first write using `CREATE TABLE IF NOT EXISTS`. Works with or without Rails
+    migrations.
+
+  ```ruby
+  # Global config (all sessions)
+  Ask::Agent.configure { |c| c.audit_log = { adapter: :active_record } }
+
+  # Per-session
+  session = Ask::Agent::Session.new(model: "gpt-4o", audit_log: { adapter: :file })
+  ```
+
+  Events logged: `session_start`, `session_end`, `turn_end`, `tool_execution_start`,
+  `tool_execution_end`, `error`, `max_turns_exceeded`, `loop_detected`,
+  `compaction_end`, `evaluation_blocked`.
+
+  Sensitive arguments (password, token, api_key, sql, etc.) are redacted automatically.
+
+- **12 tests** for AuditLog — adapter contract, event subscription, config integration,
+  sensitive arg redaction, legacy hook interface.
+
+### Changed
+
+- `Session#initialize` now accepts `audit_log:` parameter and falls back to
+  `Ask::Agent.configuration.audit_log`.
+- `Ask::Agent::Configuration#audit_log` — new accessor for global audit log config.
+
+## [0.21.0] — 2026-07-26
+
+- Version bump only.
+
+## [0.20.0] — 2026-07-26
+
+### Added
+
+- **`Events::ThinkingDelta`** — new event emitted when a chunk has thinking/reasoning
+  content. The loop already received chunks with `.thinking` data from providers like
+  DeepSeek and Claude, but it wasn't exposed as a dedicated event. Now it is.
+- **`Ask::Agent::Streaming`** — framework-agnostic SSE streaming module. Returns a
+  Rack-compatible Enumerator that yields SSE-formatted strings as the agent runs.
+  Works with any Rack server without requiring Rails or ActionController::Live.
+
+  Two modes:
+  - **Enumerable mode** (no block) — for Rack/Roda/Sinatra:
+    ```ruby
+    stream = Ask::Agent::Streaming.run(session, prompt)
+    [200, { "Content-Type" => "text/event-stream" }, stream]
+    ```
+  - **Block mode** — for Rails `ActionController::Live::SSE`:
+    ```ruby
+    Ask::Agent::Streaming.run(session, prompt) do |type, data|
+      sse.write(data, event: type)
+    end
+    ```
+
+- **19 tests** for Streaming + ThinkingDelta — Enumerator mode, block mode, custom
+  event maps, error handling, SSE line format, event structure.
+
 ## [0.19.0] — 2026-07-26
 
 ### Added

data/README.md

@@ -218,6 +218,7 @@ c.middleware.use :model_fallback,
 ```ruby
 Ask::Agent.configure do |c|
   c.default_model = "claude-sonnet-4"
+  c.default_provider = :anthropic
   c.default_max_turns = 50
   c.compactor_enabled = true
   c.compactor_threshold = 0.8
@@ -226,6 +227,12 @@ Ask::Agent.configure do |c|
 end
 ```
 
+`default_provider` pins which provider serves the default model when the
+model name doesn't uniquely identify one (for example, the same model id
+registered under multiple OpenAI-compatible providers). A `provider:`
+passed to `Session.new` or declared in an agent `Definition` always wins
+over the global default.
+
 ## Persistence
 
 ```ruby

data/lib/ask/agent/chat.rb

@@ -19,7 +19,7 @@ module Ask
     ToolCallInfo = Data.define(:id, :name, :arguments)
 
     ChatChunk = Data.define(:content, :tool_calls, :thinking, :input_tokens, :output_tokens) do
-      def tool_call? = !tool_calls.empty?
+      def tool_call? = !tool_calls.to_a.empty?
     end
 
     class Chat
@@ -68,7 +68,8 @@ module Ask
           metadata: {
             input_tokens: response_msg.input_tokens,
             output_tokens: response_msg.output_tokens,
-            cost: response_msg.cost
+            cost: response_msg.cost,
+            thinking: response_msg.thinking
           }.compact
         )
 
@@ -115,7 +116,7 @@ module Ask
       end
 
       def build_provider
-        slug = @provider_override&.to_s || @model_info.provider
+        slug = @provider_override&.to_s || Ask::Agent.configuration.default_provider&.to_s || @model_info.provider
         klass = Ask::Provider.resolve(slug)
         klass.new(provider_config(slug))
       end
@@ -255,12 +256,17 @@ module Ask
       def accumulate_tool_calls(raw_chunk, calls_acc)
         return unless raw_chunk.tool_call?
 
-        raw_chunk.tool_calls.each do |tc|
-          idx = tc[:index] || 0
-          calls_acc[idx] ||= { id: tc[:id], name: tc[:name], arguments: +"" }
-          calls_acc[idx][:id] ||= tc[:id]
-          calls_acc[idx][:name] ||= tc[:name]
-          calls_acc[idx][:arguments] << tc[:arguments].to_s if tc[:arguments]
+        tool_calls = raw_chunk.tool_calls
+        return unless tool_calls.respond_to?(:each)
+
+        tool_calls.each do |tc|
+          next unless tc.respond_to?(:[])
+          idx = tc[:index] || tc["index"] || 0
+          calls_acc[idx] ||= { id: tc[:id] || tc["id"], name: tc[:name] || tc["name"], arguments: +"" }
+          calls_acc[idx][:id] ||= tc[:id] || tc["id"]
+          calls_acc[idx][:name] ||= tc[:name] || tc["name"]
+          arguments = tc[:arguments] || tc["arguments"]
+          calls_acc[idx][:arguments] << arguments.to_s if arguments
         end
       end
 
@@ -279,14 +285,21 @@ module Ask
 
       def build_tool_call_hash(raw_calls)
         hash = {}
+        return hash unless raw_calls.respond_to?(:each)
+
         raw_calls.each do |tc|
-          id = tc[:id] || tc["id"]
-          next unless id
-          hash[id] = ToolCallInfo.new(
-            id: id,
-            name: tc[:name] || tc["name"] || "",
-            arguments: tc[:arguments] || tc["arguments"] || ""
-          )
+          # Provider tool calls come as an Array of Hashes.
+          # A Hash argument (key-value pairs) means the caller passed
+          # a Hash instead of an Array — iterate values instead.
+          if tc.is_a?(Hash)
+            id = tc[:id] || tc["id"]
+            next unless id
+            hash[id] = ToolCallInfo.new(
+              id: id,
+              name: tc[:name] || tc["name"] || "",
+              arguments: tc[:arguments] || tc["arguments"] || ""
+            )
+          end
         end
         hash
       end
@@ -298,7 +311,7 @@ module Ask
           content: stream.accumulated_text,
           tool_calls: build_current_tool_calls(calls_acc),
           tool_results: {},
-          thinking: stream.chunks.filter_map(&:thinking).last,
+          thinking: stream.chunks.filter_map(&:thinking).join,
           input_tokens: tokens[:input],
           output_tokens: tokens[:output],
           cost: cost

data/lib/ask/agent/configuration.rb

@@ -3,9 +3,10 @@
 module Ask
   module Agent
     class Configuration
-      attr_accessor :default_model, :default_max_turns, :compactor_enabled,
-                    :compactor_threshold, :parallel_tool_execution, :max_tool_retries,
-                    :prompt_caching, :default_evaluator_model
+      attr_accessor :default_model, :default_provider, :default_max_turns,
+                    :compactor_enabled, :compactor_threshold, :parallel_tool_execution,
+                    :max_tool_retries, :prompt_caching, :default_evaluator_model,
+                    :audit_log
 
       # @return [Middleware::Pipeline] the middleware pipeline for provider calls
       attr_reader :middleware

data/lib/ask/agent/extensions/audit_log/active_record_writer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Extensions
+      class AuditLog
+        # ActiveRecord adapter for the audit log.
+        # Auto-creates the +ask_audit_logs+ table on first write using
+        # CREATE TABLE IF NOT EXISTS, so it works with or without Rails
+        # migrations. Rails users can also run:
+        #
+        #   rails generate ask_rails:install
+        #
+        # to get a proper migration file. The migration uses
+        # +if_not_exists: true+ so it won't conflict with auto-creation.
+        class ActiveRecordWriter < Adapter
+          TABLE_NAME = "ask_audit_logs"
+
+          def initialize
+            @table_checked = false
+            @mutex = Mutex.new
+          end
+
+          def write(entry)
+            return unless defined?(ActiveRecord::Base)
+
+            ensure_table!
+            conn = ActiveRecord::Base.connection
+            conn.execute(
+              "INSERT INTO #{TABLE_NAME} (session_id, event_type, data, timestamp, created_at, updated_at) " \
+              "VALUES (#{quote(entry[:session_id])}, #{quote(entry[:event_type])}, " \
+              "#{quote(entry[:data].to_json)}, #{quote(entry[:timestamp])}, " \
+              "#{quote(Time.now.utc.iso8601(3))}, #{quote(Time.now.utc.iso8601(3))})"
+            )
+          rescue ActiveRecord::ActiveRecordError => e
+            warn "[ask-agent] AuditLog::ActiveRecordWriter write failed: #{e.message}"
+          end
+
+          private
+
+          def ensure_table!
+            return if @table_checked
+
+            @mutex.synchronize do
+              return if @table_checked
+              conn = ActiveRecord::Base.connection
+              unless conn.table_exists?(TABLE_NAME)
+                conn.create_table(TABLE_NAME, if_not_exists: true) do |t|
+                  t.string :session_id, null: false
+                  t.string :event_type, null: false
+                  t.jsonb :data, default: {}
+                  t.datetime :timestamp, null: false
+                  t.timestamps
+
+                  t.index [:session_id, :event_type]
+                  t.index :timestamp
+                end
+              end
+              @table_checked = true
+            end
+          end
+
+          def quote(value)
+            ActiveRecord::Base.connection.quote(value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,40 +1,187 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Ask
   module Agent
     module Extensions
+      # Event-driven audit log for agent sessions.
+      #
+      # Subscribes to all session events and writes them to a configurable
+      # adapter. Ships with an ActiveRecord adapter; custom adapters can
+      # implement the simple {Adapter} interface.
+      #
+      # @example Enable globally (ActiveRecord)
+      #   Ask::Agent.configure do |c|
+      #     c.audit_log = { adapter: :active_record }
+      #   end
+      #
+      # @example Per-session with custom adapter
+      #   Session.new(model: "gpt-4o", audit_log: { adapter: MyWriter.new })
+      #
       class AuditLog
-        def initialize(output: $stdout, path: nil)
-          @entries = []
-          @mutex = Mutex.new
+        # Pluggable adapter interface.
+        # Implement +write(entry)+ to persist a structured event hash.
+        class Adapter
+          def write(entry)
+            raise NotImplementedError
+          end
+        end
 
-          if path
-            @io = File.open(path, "a")
-            @io.sync = true
-          else
-            @io = output
+        # Built-in adapter: appends JSON lines to a file.
+        class FileAdapter < Adapter
+          def initialize(path: "tmp/agent_audit.jsonl")
+            @path = path
+            @mutex = Mutex.new
+          end
+
+          def write(entry)
+            @mutex.synchronize do
+              File.open(@path, "a") { |f| f.puts(JSON.generate(entry)) }
+            end
+          end
+        end
+
+        # Event types that get persisted (not every delta/stream event).
+        STORED_EVENTS = {
+          Events::SessionStart       => "session_start",
+          Events::SessionEnd         => "session_end",
+          Events::TurnEnd            => "turn_end",
+          Events::ToolExecutionStart => "tool_execution_start",
+          Events::ToolExecutionEnd   => "tool_execution_end",
+          Events::Error              => "error",
+          Events::MaxTurnsExceeded   => "max_turns_exceeded",
+          Events::LoopDetected       => "loop_detected",
+          Events::CompactionEnd      => "compaction_end",
+          Events::EvaluationBlocked  => "evaluation_blocked"
+        }.freeze
+
+        def initialize(session, adapter: nil)
+          @session = session
+          @session_id = session.id
+          @adapter = resolve(adapter)
+          subscribe! if @adapter
+        end
+
+        # Subscribe to session events and log stored event types.
+        def subscribe!
+          @session.on_event do |event|
+            type = STORED_EVENTS[event.class]
+            next unless type
+
+            write_entry(type, extract(event))
           end
         end
 
+        # Legacy hook interface — kept for backward compatibility.
+        # Called by the hooks system after each tool execution.
         def after_tool_call(tool_call, result, _context)
-          entry = {
-            timestamp: Time.now.utc.iso8601(3),
+          write_entry("tool_call", {
             tool_name: tool_call.name,
             arguments: tool_call.arguments,
-            result: result,
-            duration: result[:duration_ms]
-          }
+            result: result&.to_s&.to_s[0, 500],
+            duration_ms: result[:duration_ms]
+          })
+        end
 
-          @mutex.synchronize do
-            @entries << entry
-            @io.puts entry.to_json
-          end
+        private
 
+        def resolve(adapter)
+          return nil if adapter.nil?
+          return adapter if adapter.is_a?(Adapter)
+
+          case adapter
+          when :active_record
+            require "ask/agent/extensions/audit_log/active_record_writer"
+            AuditLog::ActiveRecordWriter.new
+          when Hash
+            resolve(adapter[:adapter] || adapter[:writer])
+          when Symbol, String
+            # Try to load adapter by convention:
+            # :active_record → ask/agent/extensions/audit_log/active_record_writer
+            name = adapter.to_s
+            begin
+              require "ask/agent/extensions/audit_log/#{name}_writer"
+              klass_name = name.split("_").map(&:capitalize).join
+              klass = AuditLog.const_get(klass_name)
+              klass.new
+            rescue LoadError
+              warn "[ask-agent] AuditLog: adapter not found: #{name}"
+              nil
+            end
+          else
+            adapter
+          end
+        rescue LoadError
+          warn "[ask-agent] AuditLog: ActiveRecord adapter not available"
           nil
         end
 
-        def entries
-          @mutex.synchronize { @entries.dup }
+        def write_entry(type, data)
+          entry = {
+            session_id: @session_id,
+            event_type: type,
+            timestamp: Time.now.utc.iso8601(3),
+            data: data
+          }
+          @adapter.write(entry)
+        rescue => e
+          warn "[ask-agent] AuditLog write failed: #{e.message}"
+        end
+
+        def extract(event)
+          case event
+          when Events::SessionStart
+            {}
+          when Events::SessionEnd
+            {
+              turn_count: event.turn_count,
+              tool_calls_made: event.tool_calls_made,
+              input_tokens: event.input_tokens,
+              output_tokens: event.output_tokens,
+              cost: event.cost
+            }
+          when Events::TurnEnd
+            {
+              turn_number: event.turn_number,
+              tool_results_count: event.tool_results&.length || 0,
+              input_tokens: event.input_tokens,
+              output_tokens: event.output_tokens,
+              cost: event.cost
+            }
+          when Events::ToolExecutionStart
+            { name: event.name, id: event.id, args: safe_args(event.arguments) }
+          when Events::ToolExecutionEnd
+            {
+              name: event.name, id: event.id,
+              duration_ms: event.duration_ms,
+              is_error: event.is_error,
+              result: event.result&.to_s&.to_s[0, 500]
+            }
+          when Events::Error
+            { message: event.error, recoverable: event.recoverable }
+          when Events::MaxTurnsExceeded
+            { max_turns: event.max_turns }
+          when Events::LoopDetected
+            { tool_name: event.tool_name, repeated_count: event.repeated_count }
+          when Events::CompactionEnd
+            { tokens_before: event.tokens_before, tokens_after: event.tokens_after }
+          when Events::EvaluationBlocked
+            { feedback: event.feedback, scores: event.scores }
+          else
+            {}
+          end
+        end
+
+        def safe_args(args)
+          return {} unless args.is_a?(Hash)
+
+          safe = args.dup
+          %w[password secret token api_key key auth_token access_token sql command].each do |sensitive|
+            safe[sensitive] = "[REDACTED]" if safe.key?(sensitive)
+            safe[sensitive.to_sym] = "[REDACTED]" if safe.key?(sensitive.to_sym)
+          end
+          safe
         end
       end
     end

data/lib/ask/agent/loop.rb

@@ -32,10 +32,13 @@ module Ask
           end
 
           if chunk.tool_call?
-            chunk.tool_calls.each do |id, tc|
-              event_emitter.emit(Events::ToolCallDelta.new(
-                name: tc.name, arguments: tc.arguments, id: tc.id
-              ))
+            calls = chunk.tool_calls
+            if calls.respond_to?(:each)
+              calls.each do |id, tc|
+                event_emitter.emit(Events::ToolCallDelta.new(
+                  name: tc.name, arguments: tc.arguments, id: tc.id
+                ))
+              end
             end
           end
         end

data/lib/ask/agent/session.rb

@@ -21,7 +21,7 @@ module Ask
                      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, evaluator: nil, **chat_options)
+                     agent_dir: nil, evaluator: nil, audit_log: nil, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -47,6 +47,7 @@ module Ask
         @tool_executor = ToolExecutor.new(max_retries: max_tool_retries, parallel: parallel_tools)
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
+        @audit_log = build_audit_log(audit_log)
 
         @system_context = build_system_context(system_prompt)
         apply_system_context
@@ -229,6 +230,10 @@ module Ask
           try_auto_meta_agent
         end
 
+        # Capture messages before emitting SessionEnd so event handlers
+        # can access agent.messages during the callback
+        @messages = @chat.messages.dup
+
         emit(Events::SessionEnd.new(
           result: response,
           turn_count: @turn_count,
@@ -237,7 +242,6 @@ module Ask
           output_tokens: @total_output_tokens,
           cost: @total_cost
         ))
-        @messages = @chat.messages.dup
 
         response
       end
@@ -331,6 +335,12 @@ module Ask
 
       private
 
+      def build_audit_log(config)
+          config ||= Ask::Agent.configuration.audit_log
+          return nil unless config
+          Ask::Agent::Extensions::AuditLog.new(self, adapter: config)
+        end
+
       def build_chat(model, system_prompt, tools, **chat_options)
         if model.respond_to?(:ask)
           model

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.20.0"
+    VERSION = "0.23.0"
   end
 end

data/lib/ask/agent.rb

@@ -7,6 +7,7 @@ require "time"
 require "ask/skills"
 require "ask-llm-providers"
 require "ask-tools"
+require "ask-state-providers"
 
 module Ask
   module Agent

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -174,6 +174,7 @@ files:
 - lib/ask/agent/evaluator.rb
 - lib/ask/agent/events.rb
 - lib/ask/agent/extensions/audit_log.rb
+- lib/ask/agent/extensions/audit_log/active_record_writer.rb
 - lib/ask/agent/extensions/permissions.rb
 - lib/ask/agent/extensions/rate_limiter.rb
 - lib/ask/agent/hooks.rb