ask-agent 0.1.0

data/lib/ask/agent/telemetry.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+
+module Ask
+  module Agent
+    class Telemetry
+      TELEMETRY_DIR = File.expand_path("~/.ask/agent/telemetry")
+      EVENT_TYPES = %i[tool_error loop_detected max_turns_exceeded compaction_end reflection_end].freeze
+
+      attr_reader :enabled
+
+      def initialize(enabled: true, dir: nil)
+        @enabled = enabled
+        @dir = dir || TELEMETRY_DIR
+        @mutex = Mutex.new
+      end
+
+      def log(event_type, data)
+        return unless @enabled
+        return unless EVENT_TYPES.include?(event_type)
+
+        entry = {
+          timestamp: Time.now.utc.iso8601(3),
+          event_type: event_type,
+          session_id: data[:session_id],
+          details: data.reject { |k, _| k == :session_id }
+        }
+
+        dir = File.join(@dir, event_type.to_s)
+        FileUtils.mkdir_p(dir)
+
+        filename = "#{entry[:timestamp].tr(':', '-')}_#{SecureRandom.hex(4)}.json"
+
+        @mutex.synchronize do
+          File.write(File.join(dir, filename), JSON.pretty_generate(entry) + "\n")
+        end
+      end
+
+      def read(event_type = nil)
+        return {} unless File.directory?(@dir)
+
+        entries = []
+        dirs = event_type ? [File.join(@dir, event_type.to_s)] : Dir[File.join(@dir, "*")].select { |d| File.directory?(d) }
+
+        dirs.each do |dir|
+          Dir[File.join(dir, "*.json")].sort.each do |file|
+            entries << JSON.parse(File.read(file))
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        entries.group_by { |e| e["event_type"] }
+      end
+
+      def track_recommendation(recommendation)
+        return unless @enabled
+
+        entry = recommendation.to_h.merge(
+          recommendation_id: "rec_#{SecureRandom.hex(8)}",
+          timestamp: Time.now.utc.iso8601(3),
+          status: "open"
+        )
+
+        rec_dir = File.join(@dir, "recommendations")
+        FileUtils.mkdir_p(rec_dir)
+
+        filename = "#{entry[:timestamp].tr(':', '-')}_#{entry[:recommendation_id]}.json"
+
+        @mutex.synchronize do
+          File.write(File.join(rec_dir, filename), JSON.pretty_generate(entry) + "\n")
+        end
+
+        entry[:recommendation_id]
+      end
+
+      def track_resolution(recommendation_id)
+        return unless @enabled
+
+        rec_dir = File.join(@dir, "recommendations")
+        return unless File.directory?(rec_dir)
+
+        Dir[File.join(rec_dir, "*.json")].each do |file|
+          entry = JSON.parse(File.read(file))
+          next unless entry["recommendation_id"] == recommendation_id
+
+          entry["status"] = "resolved"
+          entry["resolved_at"] = Time.now.utc.iso8601(3)
+
+          @mutex.synchronize do
+            File.write(file, JSON.pretty_generate(entry) + "\n")
+          end
+          return true
+        rescue JSON::ParserError
+          nil
+        end
+
+        false
+      end
+
+      def read_recommendations(status: nil)
+        rec_dir = File.join(@dir, "recommendations")
+        return [] unless File.directory?(rec_dir)
+
+        entries = Dir[File.join(rec_dir, "*.json")].sort.map do |file|
+          JSON.parse(File.read(file))
+        rescue JSON::ParserError
+          nil
+        end.compact
+
+        return entries unless status
+        entries.select { |e| e["status"] == status }
+      end
+
+      def increment_session_count!
+        return unless @enabled
+
+        FileUtils.mkdir_p(@dir)
+        path = File.join(@dir, "session_counter.json")
+
+        @mutex.synchronize do
+          count = File.exist?(path) ? JSON.parse(File.read(path))["count"] : 0
+          File.write(path, JSON.pretty_generate({ count: count + 1, updated_at: Time.now.utc.iso8601(3) }) + "\n")
+        end
+      end
+
+      def session_count
+        return 0 unless @enabled
+
+        path = File.join(@dir, "session_counter.json")
+        return 0 unless File.exist?(path)
+
+        JSON.parse(File.read(path))["count"]
+      rescue JSON::ParserError
+        0
+      end
+
+      def reset_session_count!
+        return unless @enabled
+
+        path = File.join(@dir, "session_counter.json")
+        @mutex.synchronize do
+          File.write(path, JSON.pretty_generate({ count: 0, updated_at: Time.now.utc.iso8601(3) }) + "\n")
+        end
+      end
+
+      def clear!
+        return unless File.directory?(@dir)
+
+        Dir[File.join(@dir, "**/*.json")].each { |f| File.delete(f) }
+      end
+    end
+  end
+end

data/lib/ask/agent/tool_abort_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    class ToolAbortController
+      def initialize
+        @aborted = false
+        @mutex = Mutex.new
+      end
+
+      def abort!
+        @mutex.synchronize { @aborted = true }
+      end
+
+      def aborted?
+        @mutex.synchronize { @aborted }
+      end
+
+      def reset!
+        @mutex.synchronize { @aborted = false }
+      end
+    end
+  end
+end

data/lib/ask/agent/tool_executor.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    class ToolExecutor
+      CRITICAL_ERROR_CLASSES = %w[
+        Ask::Unauthorized
+        Ask::Forbidden
+        Ask::PaymentRequired
+      ].freeze
+
+      attr_reader :total_executions
+
+      def initialize(max_retries: 3, parallel: true)
+        @max_retries = max_retries
+        @parallel = parallel
+        @total_executions = 0
+      end
+
+      attr_writer :telemetry
+
+      def execute(tool_calls, tools, hooks:, event_emitter:, session_id: nil)
+        return [] if tool_calls.empty?
+
+        @total_executions = 0
+        @session_id = session_id
+        sibling_abort = ToolAbortController.new
+
+        if @parallel
+          execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort)
+        else
+          execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort)
+        end
+      end
+
+      def execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
+        threads = []
+        mutex = Mutex.new
+        results = {}
+
+        tool_calls.each do |id, tool_call|
+          threads << Thread.new do
+            begin
+              if sibling_abort.aborted?
+                mutex.synchronize { results[id] = aborted_result(tool_call) }
+                next
+              end
+
+              result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort)
+              mutex.synchronize { results[id] = result }
+
+              # Stream result back as it completes
+              result_callback&.call(tool_call.id, result)
+
+              if result[:critical_failure]
+                sibling_abort.abort!
+              end
+            rescue => e
+              mutex.synchronize do
+                results[id] = {
+                  tool_name: tool_call.name, message: e.message,
+                  status: "error", is_error: true, critical_failure: false
+                }
+              end
+              result_callback&.call(tool_call.id, results[id])
+            end
+          end
+        end
+
+        threads.each(&:join)
+        tool_calls.keys.map { |id| results[id] }.compact
+      end
+
+      def execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort)
+        results = []
+        tool_calls.each do |id, tool_call|
+          break if sibling_abort.aborted?
+
+          result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort)
+          results << result
+          break if result[:critical_failure]
+        end
+        results
+      end
+
+      private
+
+      def execute_single_tool(tool_call, tools, hooks, event_emitter, abort_controller = nil)
+        return aborted_result(tool_call) if abort_controller&.aborted?
+
+        tool = tools.find { |t| t.name == tool_call.name }
+
+        unless tool
+          return { tool_name: tool_call.name, message: "Tool not found", status: "error", is_error: true }
+        end
+
+        hook_result = hooks.run_before_tool(tool_call, {})
+        case hook_result&.dig(:action)
+        when :block
+          return { tool_name: tool_call.name, message: hook_result[:reason], status: "blocked", is_error: true }
+        when :short_circuit
+          return { tool_name: tool_call.name, **hook_result[:result], status: "short_circuited" }
+        end
+
+        return aborted_result(tool_call) if abort_controller&.aborted?
+
+        args = hook_result&.dig(:arguments) || tool_call.arguments
+
+        event_emitter.emit(Events::ToolExecutionStart.new(
+          name: tool_call.name, arguments: args, id: tool_call.id
+        ))
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = begin
+          execute_with_retry(tool, tool_call.id, args, abort_controller)
+        rescue Exception => e
+          { result: e.message, is_error: true, error: e.class.name }
+        end
+        duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).to_i
+        @total_executions += 1
+
+        return aborted_result(tool_call) if abort_controller&.aborted?
+
+        hook_result = hooks.run_after_tool(tool_call, result, {})
+        if hook_result&.dig(:action) == :transform
+          result = hook_result[:result]
+        end
+
+        is_error = result[:is_error] == true
+        critical = is_error && critical_error?(result[:error])
+
+        if is_error && @telemetry
+          @telemetry.log(:tool_error, session_id: @session_id, tool_name: tool_call.name, error_class: result[:error] || "RuntimeError", error_message: result[:result].to_s)
+        end
+
+        event_emitter.emit(Events::ToolExecutionEnd.new(
+          name: tool_call.name, id: tool_call.id, result: result, is_error: is_error, duration_ms: duration
+        ))
+
+        message = if is_error
+          tool_result = result[:result]
+          error_msg = if tool_result.is_a?(Hash) && tool_result[:error]
+            tool_result[:error].to_s
+          elsif tool_result.is_a?(String)
+            tool_result
+          else
+            result.to_s
+          end
+          "Tool #{tool_call.name} error: #{error_msg}"
+        else
+          result[:result].to_s
+        end
+
+        {
+          tool_name: tool_call.name,
+          message: message,
+          status: is_error ? "error" : "success",
+          result: result,
+          critical_failure: critical
+        }
+      end
+
+      def execute_with_retry(tool, tool_call_id, args, abort_controller = nil)
+        @max_retries.times do |attempt|
+          return { result: nil, is_error: true, error: "Aborted" } if abort_controller&.aborted?
+
+          result = try_call(tool, args)
+          return result unless result[:is_error] && retryable_error_name?(result[:error])
+
+          sleep((2 ** attempt) * 0.5 + rand(0.0..0.5))
+        end
+
+        return { result: nil, is_error: true, error: "Aborted" } if abort_controller&.aborted?
+        try_call(tool, args)
+      end
+
+      def try_call(tool, args)
+        result = tool.call(args)
+        { result: result, is_error: false }
+      rescue => e
+        { result: e.message, is_error: true, error: e.class.name }
+      end
+
+      def retryable_error_name?(error_name)
+        retryable = %w[Timeout::Error Errno::ETIMEDOUT
+                       Ask::RateLimitError Ask::ServerError
+                       Ask::RateLimitError Ask::ServiceUnavailableError]
+        retryable.include?(error_name)
+      end
+
+      def critical_error?(error_class_name)
+        return false unless error_class_name
+        CRITICAL_ERROR_CLASSES.any? { |klass| error_class_name == klass.name }
+      end
+
+      def aborted_result(tool_call)
+        {
+          tool_name: tool_call.name,
+          message: "Aborted by sibling failure",
+          status: "aborted",
+          is_error: true,
+          aborted: true
+        }
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/agent.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "fileutils"
+require "json"
+require "securerandom"
+require "time"
+
+module Ask
+  module Agent
+    class Error < StandardError; end
+    class LoopDetected < Error; end
+    class MaxTurnsExceeded < Error; end
+    class Aborted < Error; end
+    class ToolExecutionError < Error; end
+    class CompactionFailed < Error; end
+    class SessionNotPersisted < Error; end
+
+    module Extensions
+      autoload :PermissionGate, "ask/agent/extensions/permission_gate"
+      autoload :RateLimiter, "ask/agent/extensions/rate_limiter"
+      autoload :AuditLog, "ask/agent/extensions/audit_log"
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      def load_extensions
+        Dir[File.expand_path("agent/extensions/*.rb", __dir__)].each { |f| require f }
+      rescue Errno::ENOENT
+      end
+    end
+  end
+end
+
+require_relative "agent/version"
+require_relative "agent/events"
+require_relative "agent/telemetry"
+require_relative "agent/tool_abort_controller"
+require_relative "agent/session"
+require_relative "agent/loop"
+require_relative "agent/reflector"
+require_relative "agent/tool_executor"
+require_relative "agent/compactor"
+require_relative "agent/hooks"
+require_relative "agent/configuration"
+require_relative "agent/meta_agent"
+require_relative "agent/persistence/base"
+require_relative "agent/persistence/in_memory"

data/lib/ask-agent.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "ask/tools"
+require "ask/tools/shell"
+require "ask/agent"

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: ask-agent
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: ask-tools-shell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Agent loop, session management, tool execution, context compaction, hooks,
+  and extensions.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-agent.rb
+- lib/ask/agent.rb
+- lib/ask/agent/compactor.rb
+- lib/ask/agent/configuration.rb
+- lib/ask/agent/events.rb
+- lib/ask/agent/extensions/audit_log.rb
+- lib/ask/agent/extensions/permission_gate.rb
+- lib/ask/agent/extensions/rate_limiter.rb
+- lib/ask/agent/hooks.rb
+- lib/ask/agent/loop.rb
+- lib/ask/agent/meta_agent.rb
+- lib/ask/agent/persistence/base.rb
+- lib/ask/agent/persistence/in_memory.rb
+- lib/ask/agent/reflector.rb
+- lib/ask/agent/session.rb
+- lib/ask/agent/telemetry.rb
+- lib/ask/agent/tool_abort_controller.rb
+- lib/ask/agent/tool_executor.rb
+- lib/ask/agent/version.rb
+homepage: https://github.com/ask-rb/ask-agent
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Agent runtime for the ask-rb ecosystem
+test_files: []