ask-agent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a067aefe3faa67280e7ba4cde37994b52f27d5e665e86510e16ee8acf594f80
+  data.tar.gz: 4d059bcc2cf98b1fa159c4ab7eba622ba1e529063b7d517343fd3a4f59b97180
+SHA512:
+  metadata.gz: 4746d44442fbf8bdf9f67b325914cc57401857151caa2e56d5930d2134e19f03ae18d1064039e414e343539efa4c9c6be26ed2badd59898e3c5deb176f7bebe0
+  data.tar.gz: 1c8319c4cb60213a2de06b7cba0fc8443b217918586559af1c0a61e212d4cd30a58eb1d05784d4a5aca0737af65740dd4042285a8b1dc0976d4957cc426b0a5f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# ask-agent
+
+Agent runtime for the ask-rb ecosystem. The core agent loop: think → call tools → execute → feed back → repeat.
+
+Ported from `RubyLLM::Conductor` into the `Ask::Agent` namespace.
+
+## Installation
+
+```ruby
+gem "ask-agent"
+```
+
+## Quick Start
+
+```ruby
+require "ask-agent"
+
+session = Ask::Agent::Session.new(
+  model: "gpt-4o",
+  tools: [Ask::Tools::Shell::Bash, Ask::Tools::Shell::Read]
+)
+
+response = session.run("What files are in the current directory?")
+puts response
+```
+
+## Components
+
+| Component | File | Purpose |
+|---|---|---|
+| `Ask::Agent::Session` | session.rb | Full agent loop — message → tool calls → results → follow-up |
+| `Ask::Agent::Loop` | loop.rb | Turn management, loop detection, max-turn guard |
+| `Ask::Agent::ToolExecutor` | tool_executor.rb | Parallel/sequential tool execution with retry and abort |
+| `Ask::Agent::Compactor` | compactor.rb | Context window management with proactive/overflow compaction |
+| `Ask::Agent::Hooks` | hooks.rb | Before/after tool lifecycle callbacks |
+| `Ask::Agent::Events` | events.rb | Data.define event types for streaming and monitoring |
+| `Ask::Agent::Telemetry` | telemetry.rb | File-backed telemetry for error tracking |
+| `Ask::Agent::Reflector` | reflector.rb | Assistant response self-evaluation |
+| `Ask::Agent::MetaAgent` | meta_agent.rb | LLM-powered self-improvement from telemetry |
+| `Ask::Agent::Configuration` | configuration.rb | Global config: model, turns, concurrency |
+
+## Events
+
+Stream session execution in real-time:
+
+```ruby
+session.on_event do |event|
+  case event
+  when Ask::Agent::Events::TextDelta
+    print event.content
+  when Ask::Agent::Events::ToolExecutionStart
+    puts "\nRunning #{event.name}..."
+  when Ask::Agent::Events::ToolExecutionEnd
+    puts "  → #{event.duration_ms}ms #{event.is_error ? 'error' : 'ok'}"
+  end
+end
+```
+
+## Extensions
+
+Opt-in safety modules:
+
+- **PermissionGate** — Require approval for destructive tools (write, edit, bash, destroy)
+- **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::RateLimiter.new(max_calls_per_minute: 30),
+  Ask::Agent::Extensions::AuditLog.new(path: "agent.log")
+]
+
+session = Ask::Agent::Session.new(
+  model: "gpt-4o",
+  tools: [...],
+  hooks: {
+    before_tool: extensions.map(&:method(:before_tool_call)),
+    after_tool: extensions.select { |e| e.respond_to?(:after_tool_call) }.map(&:method(:after_tool_call))
+  }
+)
+```
+
+## Configuration
+
+```ruby
+Ask::Agent.configure do |c|
+  c.default_model = "claude-sonnet-4"
+  c.default_max_turns = 50
+  c.compactor_enabled = true
+  c.compactor_threshold = 0.8
+  c.parallel_tool_execution = true
+  c.max_tool_retries = 3
+end
+```
+
+## Persistence
+
+```ruby
+store = Ask::Agent::Persistence::InMemory.new
+session = Ask::Agent::Session.new(model: "gpt-4o", persistence: store)
+session.run("Hello")
+session.save  # persisted to store
+```
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/agent/compactor.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    class Compactor
+      CONTEXT_WINDOWS = {
+        "gpt-4o" => 128_000,
+        "gpt-4o-mini" => 128_000,
+        "gpt-4-turbo" => 128_000,
+        "claude-sonnet-4" => 200_000,
+        "claude-4" => 200_000,
+        "gemini-2.0-flash" => 1_048_576,
+        "gemini-2.5-pro" => 1_048_576,
+        "deepseek-v4-flash" => 1_000_000,
+        "deepseek-v4-pro" => 1_000_000,
+      }.tap { |h| h.default = 128_000 }
+
+      attr_accessor :chat, :llm
+
+      def initialize(threshold: 0.8, strategy: :proactive, llm: nil)
+        @threshold = threshold
+        @strategy = strategy
+        @llm = llm
+        @already_compacted = false
+        @overflow_recovered = false
+      end
+
+      def overflow_recovered? = @overflow_recovered
+
+      def should_compact?
+        return false unless @chat
+        current = estimate_total_tokens
+        window = context_window
+        current >= window * @threshold
+      end
+
+      def run(event_emitter: nil)
+        return unless @chat
+
+        tokens_before = estimate_total_tokens
+        event_emitter&.emit(Events::CompactionStart.new(tokens_before: tokens_before, reason: :threshold))
+        compact!
+        tokens_after = estimate_total_tokens
+        @already_compacted = true
+        event_emitter&.emit(Events::CompactionEnd.new(tokens_before: tokens_before, tokens_after: tokens_after, summary: extract_summary))
+      end
+
+      def compact!
+        return unless @chat
+        messages = @chat.messages.dup
+        return if messages.size < 6
+
+        keep_count = [messages.size, 8].min
+        recent = messages.last(keep_count)
+        older = messages.first(messages.size - keep_count)
+        return if older.empty?
+
+        summary = if @llm
+          generate_llm_summary(older) || generate_summary(older)
+        else
+          generate_summary(older)
+        end
+
+        older.size.times { @chat.messages.delete_at(0) }
+        @chat.add_message(role: :system, content: "[Previous conversation summary]: #{summary}")
+      end
+
+      def microcompact!
+        return unless @chat
+        @chat.messages.each do |msg|
+          next unless msg.role == :tool
+          msg.content = "[Tool result cleared by compaction]" if msg.content.to_s.length > 200
+        end
+      end
+
+      def recover_from_overflow
+        if @already_compacted then microcompact! else compact! end
+        @already_compacted = true
+        @overflow_recovered = true
+      end
+
+      def estimate_tokens(text)
+        (text.to_s.length / 4.0).ceil
+      end
+
+      def estimate_total_tokens
+        return 0 unless @chat
+        @chat.messages.sum { |msg| estimate_message_tokens(msg) }
+      end
+
+      def context_window
+        model = @chat.model.to_s
+        CONTEXT_WINDOWS[model]
+      end
+
+      private
+
+      def estimate_message_tokens(message)
+        base = estimate_tokens(message.content.to_s)
+        if message.tool_call? && message.respond_to?(:tool_calls) && message.tool_calls
+          base + message.tool_calls.sum { |_, tc| estimate_tokens(tc.name.to_s) + estimate_tokens(tc.arguments.to_s) }
+        else
+          base
+        end
+      end
+
+      def generate_summary(messages)
+        lines = messages.each_cons(2)
+          .select { |a, _b| a.role == :user }
+          .map { |u, a| "- Asked: #{u.content.to_s[0, 80]} → #{a.content.to_s[0, 120]}" }
+        lines.empty? ? "Previous conversation context." : lines.join("\n")
+      end
+
+      def generate_llm_summary(messages)
+        prompt = "Summarize this conversation concisely. Focus on goals accomplished, key info, decisions, and pending actions.\n\n#{serialize_conversation(messages)}"
+        response = build_llm_chat.ask(prompt)
+        text = response.content.to_s.strip
+        text.empty? ? nil : text
+      rescue
+        nil
+      end
+
+      def serialize_conversation(messages)
+        messages.map { |m|
+          role = m.role == :user ? "Human" : "Assistant"
+          content = if m.tool_call? && m.respond_to?(:tool_calls) && m.tool_calls
+                      details = m.tool_calls.map { |_, tc| "  - Called #{tc.name} with #{tc.arguments}" }.join("\n")
+                      "#{m.content}\n#{details}"
+                    elsif m.role == :tool
+                      c = m.content.to_s[0, 500]
+                      "[Tool result]: #{c}"
+                    else
+                      m.content.to_s
+                    end
+          "#{role}: #{content}"
+        }.join("\n---\n")
+      end
+
+      def build_llm_chat
+        if @llm.respond_to?(:ask) then @llm
+        elsif @llm.is_a?(String) then RubyLLM::Chat.new(model: @llm)
+        else RubyLLM::Chat.new end
+      end
+
+      def extract_summary
+        @chat.messages.each { |msg| return msg.content.to_s if msg.content.to_s.start_with?("[Previous conversation summary]") }
+        ""
+      end
+    end
+  end
+end

data/lib/ask/agent/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    class Configuration
+      attr_accessor :default_model, :default_max_turns, :compactor_enabled,
+                    :compactor_threshold, :parallel_tool_execution, :max_tool_retries
+
+      def initialize
+        @default_model = "gpt-4o"
+        @default_max_turns = 25
+        @compactor_enabled = true
+        @compactor_threshold = 0.8
+        @parallel_tool_execution = true
+        @max_tool_retries = 3
+      end
+    end
+  end
+end

data/lib/ask/agent/events.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Events
+      SessionStart = Data.define
+      SessionEnd = Data.define(:result, :turn_count, :tool_calls_made)
+
+      TurnStart = Data.define
+      TurnEnd = Data.define(:tool_results, :turn_number)
+
+      MessageStart = Data.define
+      TextDelta = Data.define(:content)
+      ToolCallDelta = Data.define(:name, :arguments, :id)
+      MessageEnd = Data.define(:tool_calls)
+
+      ToolExecutionStart = Data.define(:name, :arguments, :id)
+      ToolExecutionUpdate = Data.define(:name, :id, :partial_result)
+      ToolExecutionEnd = Data.define(:name, :id, :result, :is_error, :duration_ms)
+
+      CompactionStart = Data.define(:tokens_before, :reason)
+      CompactionEnd = Data.define(:tokens_before, :tokens_after, :summary)
+
+      LoopDetected = Data.define(:tool_name, :repeated_count)
+      MaxTurnsExceeded = Data.define(:max_turns)
+
+      ReflectionStart = Data.define(:reflection_number)
+      ReflectionDelta = Data.define(:content)
+      ReflectionEnd = Data.define(:decision, :feedback)
+
+      MetaAgentAnalysis = Data.define(:results, :count)
+
+      Error = Data.define(:error, :recoverable)
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Extensions
+      class AuditLog
+        def initialize(output: $stdout, path: nil)
+          @entries = []
+          @mutex = Mutex.new
+
+          if path
+            @io = File.open(path, "a")
+            @io.sync = true
+          else
+            @io = output
+          end
+        end
+
+        def after_tool_call(tool_call, result, _context)
+          entry = {
+            timestamp: Time.now.utc.iso8601(3),
+            tool_name: tool_call.name,
+            arguments: tool_call.arguments,
+            result: result,
+            duration: result[:duration_ms]
+          }
+
+          @mutex.synchronize do
+            @entries << entry
+            @io.puts entry.to_json
+          end
+
+          nil
+        end
+
+        def entries
+          @mutex.synchronize { @entries.dup }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+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
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Extensions
+      class RateLimiter
+        def initialize(max_calls_per_minute: 20, max_tool_calls_per_turn: 5)
+          @max_calls_per_minute = max_calls_per_minute
+          @max_tool_calls_per_turn = max_tool_calls_per_turn
+          @turn_calls = 0
+          @minute_window = []
+          @mutex = Mutex.new
+        end
+
+        def before_tool_call(tool_call, _context)
+          now = Time.now
+
+          @mutex.synchronize do
+            @turn_calls += 1
+
+            if @turn_calls > @max_tool_calls_per_turn
+              return { action: :block, reason: "Exceeded #{@max_tool_calls_per_turn} tool calls per turn" }
+            end
+
+            @minute_window << now
+            @minute_window.reject! { |t| now - t > 60 }
+
+            if @minute_window.size > @max_calls_per_minute
+              return { action: :block, reason: "Exceeded #{@max_calls_per_minute} tool calls per minute" }
+            end
+          end
+
+          { action: :proceed }
+        end
+
+        def reset_turn!
+          @mutex.synchronize { @turn_calls = 0 }
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/hooks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    class Hooks
+      def initialize(hooks = {})
+        @before_tool = Array(hooks[:before_tool])
+        @after_tool = Array(hooks[:after_tool])
+      end
+
+      def run_before_tool(tool_call, context)
+        result = nil
+        @before_tool.each do |hook|
+          result = hook.call(tool_call, context)
+          break if result.is_a?(Hash) && result[:action] != :proceed
+        end
+        result
+      end
+
+      def run_after_tool(tool_call, result, context)
+        final = nil
+        @after_tool.each do |hook|
+          final = hook.call(tool_call, result, context)
+          break if final.is_a?(Hash) && final[:action] == :block
+        end
+        final
+      end
+    end
+  end
+end

data/lib/ask/agent/loop.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    class Loop
+      LOOP_DETECTION_WINDOW = 3
+      MAX_CONSECUTIVE_TOOL_TURNS = 6
+
+      attr_reader :turn_count
+
+      def initialize(max_turns: 25)
+        @max_turns = max_turns
+        @turn_count = 0
+        @recent_results = []
+        @loop_detected = false
+        @consecutive_tool_turns = 0
+      end
+
+      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil)
+        raise MaxTurnsExceeded if @turn_count >= @max_turns
+
+        event_emitter.emit(Events::TurnStart.new)
+
+        response = chat.ask(message) do |chunk|
+          if chunk.content.to_s.strip.length > 0
+            event_emitter.emit(Events::TextDelta.new(content: chunk.content))
+          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
+              ))
+            end
+          end
+        end
+
+        event_emitter.emit(Events::MessageEnd.new(tool_calls: response.tool_call?))
+        @turn_count += 1
+
+        unless response.tool_call?
+          @consecutive_tool_turns = 0
+          return response.content.to_s
+        end
+
+        @consecutive_tool_turns += 1
+
+        # Execute tools with concurrent result streaming
+        tool_results = tool_executor.execute_parallel(
+          response.tool_calls, tools, hooks, event_emitter, ToolAbortController.new
+        ) do |tool_call_id, result|
+          # Add each tool result as it completes (concurrent streaming)
+          tc = response.tool_calls[tool_call_id]
+          chat.add_message(role: :tool, content: result[:message].to_s, tool_call_id: tool_call_id) if tc
+        end
+
+        # Check loop detection
+        if loop_detected?(tool_results)
+          raise LoopDetected, tool_results.last[:tool_name]
+        end
+
+        if @consecutive_tool_turns >= MAX_CONSECUTIVE_TOOL_TURNS
+          summary = tool_results.map { |r| r[:message].to_s.truncate(80) }.first(2).join("; ")
+          return "Based on my investigation: #{summary}"
+        end
+
+        event_emitter.emit(Events::TurnEnd.new(tool_results: tool_results, turn_number: @turn_count))
+
+        if compactor && compactor.should_compact?
+          compactor.run(event_emitter: event_emitter)
+        end
+
+        raise MaxTurnsExceeded if @turn_count >= @max_turns
+
+        # Recursive call — LLM processes tool results
+        run_turn(
+          chat: chat,
+          message: "",
+          tools: tools,
+          tool_executor: tool_executor,
+          compactor: compactor,
+          hooks: hooks,
+          event_emitter: event_emitter,
+          session_id: session_id
+        )
+      end
+
+      def reset!
+        @turn_count = 0
+        @recent_results = []
+        @loop_detected = false
+      end
+
+      private
+
+      def loop_detected?(results)
+        return false if results.empty?
+
+        results.each do |result|
+          signature = [result[:tool_name], result[:message].to_s.strip]
+          @recent_results << signature
+          @recent_results.shift if @recent_results.size > LOOP_DETECTION_WINDOW
+
+          recent = @recent_results.last(LOOP_DETECTION_WINDOW)
+          if recent.size >= LOOP_DETECTION_WINDOW && recent.uniq.size == 1
+            @loop_detected = true
+            return true
+          end
+        end
+        false
+      end
+    end
+  end
+end