ask-agent 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ad6219a4374a7aeb4688533bcf7a0a68ebb166de2d96d2e9953eb6814fe5c5
-  data.tar.gz: 89e4e0413d96f90dd30d4203fa4023331663b2818a5df89c0a60a6975fb8bcb9
+  metadata.gz: f95edab12d96da68593e426829ac2507682b4b5620b5ec0b09269062bf168bd9
+  data.tar.gz: 7353fff33dba2ebff749df32d4c079759f1f4b2eca9193a5299fe9ec7238966c
 SHA512:
-  metadata.gz: 9557223b85bc04778cd6821a9b7807818e06ac85124d95f79469db613a7a23d8e8317db5e6454517adf5b67fd68806eafc4ec145f8c3ea08d01de93d4f939a91
-  data.tar.gz: 53d3a056d6c8004bdd32536f3781bae6a0bee21bd12f1af12bc3eefab02e3f229df6109c8f5f2c6802229177aa28c27a17804bb348e93c4898adce62289222d5
+  metadata.gz: 3e3dc6f6cae44b0c2f36e12c9253b3f21e97a17634907754cc1d2ea8930bd8bcc54b2f65ef2194dae9e1e60d4a721d8071a677f3f0bbfa0d99d68515c0da82b9
+  data.tar.gz: ab443967abf274b113b9ebd8f2901feffa1cf2d7e1436e6a14df8d1dbb87fa1f204d0cb97d2d567858e89631c0b08ed97bf4183174c6ffce97aee363ffa0f724

data/CHANGELOG.md

@@ -1,3 +1,68 @@
+## [0.8.0] — 2026-07-21
+
+### Added
+
+- **Provider-executed tool support in the agent loop** — `ResponseMessage` now carries a `tool_results` field for pre-computed results from provider-executed tools (e.g. OpenAI web search, file search, code interpreter). The `Loop` detects these results, adds them directly to the conversation without local execution, then proceeds with any remaining user tool calls.
+
+  ```ruby
+  agent = Ask::Agent.new("health_check")
+  agent.run("Search the web for server status")
+  # web_search runs on OpenAI's side; results come back pre-computed
+  ```
+
+### Changed
+
+- **`ResponseMessage`** added `tool_results` field (default `{}`). All existing call sites are compatible via keyword argument defaults.
+- **`Loop#run_turn`** — separates provider-executed results from user tool calls. Provider results are added to the conversation immediately. User tool calls continue to be executed locally via `ToolExecutor`.
+- **OpenAI provider** — `split_tools` separates `Ask::ProviderTool` objects from regular tools. `format_responses_tools` converts provider tools to the Responses API format. When provider tools are present, the Responses API endpoint is used instead of Chat Completions.
+
+### Tested
+
+- 13 new integration tests: loop handling with mixed tool types, provider-only tools, tool splitting, Responses API formatting.
+- Full suite: 329 tests, 592 assertions — 0 failures.
+
+## [0.7.0] — 2026-07-21
+
+### Added
+
+- **Agent definitions — `Ask::Agent::Definition`** — Declarative agent configuration via subclassing. Define agents in `agents/<name>/agent.rb` or `app/agents/<name>/agent.rb`. The directory name becomes the agent name. Instructions auto-load from a sibling `instructions.md`.
+
+  ```ruby
+  # agents/health_check/agent.rb
+  class HealthCheckAgent < Ask::Agent::Definition
+    model "gpt-4o"
+    tools :bash, :read, :grep
+    schedule "every 5 minutes"
+  end
+  ```
+
+- **`Ask::Agent.new(name)`** — Create a configured `Session` from a named definition. Discovers agents from `agents/` and `app/agents/` automatically on first call.
+
+  ```ruby
+  agent = Ask::Agent.new("health_check")
+  agent.run("Check server health")
+  ```
+
+- **`Ask::Agent.definitions`** — Returns all discovered definitions as a hash keyed by agent name. Each entry is `[Definition_subclass, directory_path]`.
+
+- **`Ask::Agent.rediscover!`** — Force re-discovery when agent files change.
+
+- **Shared tools** — `agents/shared/tools/*.rb` are auto-discovered and available to all agents in the same project.
+
+- **`askr` CLI** — New command-line tool for running, listing, scheduling, and scaffolding agents.
+
+  ```bash
+  askr list                    # List all discovered agents
+  askr run health_check        # Run an agent (interactive if no prompt)
+  askr schedule                # Start the scheduler for all scheduled agents
+  askr new deploy_bot          # Scaffold a new agent directory
+  ```
+
+### Changed
+
+- **New dependency** — Ask::Agent::CLI module added to the lib path. `exe/askr` is registered as a gem executable.
+- **Test fixture agents** added under `test/fixtures/agents/` and `test/fixtures/app/agents/` for discovery testing.
+
 ## [0.6.1] — 2026-07-21
 
 ### Changed

data/exe/askr

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# askr — CLI for the ask-rb agent ecosystem.
+#
+# Usage:
+#   askr run <agent-name> [prompt]      Run an agent with an optional prompt
+#   askr list                           List all discovered agents
+#   askr schedule                        Start the scheduler for recurring agents
+#   askr new <agent-name>               Scaffold a new agent directory
+#   askr help                            Show this help
+
+require "ask/agent"
+
+Ask::Agent::CLI.run(ARGV)

data/lib/ask/agent/chat.rb

@@ -4,7 +4,14 @@ module Ask
   module Agent
     # Response message returned by {Chat#ask}.
     # Includes token counts and cost when available from the provider.
-    ResponseMessage = Data.define(:content, :tool_calls, :thinking, :input_tokens, :output_tokens, :cost) do
+    # +tool_calls+ are calls that need local execution.
+    # +tool_results+ are pre-computed results from provider-executed tools.
+    ResponseMessage = Data.define(:content, :tool_calls, :tool_results, :thinking, :input_tokens, :output_tokens, :cost) do
+      def initialize(content:, tool_calls: {}, tool_results: {}, thinking: nil, input_tokens: nil, output_tokens: nil, cost: nil)
+        super(content: content, tool_calls: tool_calls, tool_results: tool_results, thinking: thinking,
+              input_tokens: input_tokens, output_tokens: output_tokens, cost: cost)
+      end
+
       def tool_call? = !tool_calls.empty?
       def to_s = content.to_s
     end
@@ -286,6 +293,7 @@ module Ask
         ResponseMessage.new(
           content: stream.accumulated_text,
           tool_calls: build_current_tool_calls(calls_acc),
+          tool_results: {},
           thinking: stream.chunks.filter_map(&:thinking).last,
           input_tokens: tokens[:input],
           output_tokens: tokens[:output],
@@ -300,9 +308,11 @@ module Ask
         input_tokens = metadata[:input_tokens] || metadata["input_tokens"]
         output_tokens = metadata[:output_tokens] || metadata["output_tokens"]
         cost = calculate_cost(input_tokens, output_tokens)
+        tool_results = metadata[:provider_results] || metadata["provider_results"] || {}
         ResponseMessage.new(
           content: msg.content.to_s,
           tool_calls: tool_calls,
+          tool_results: tool_results,
           thinking: thinking,
           input_tokens: input_tokens,
           output_tokens: output_tokens,

data/lib/ask/agent/cli.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module CLI
+      module_function
+
+      def run(argv)
+        case argv.first
+        when "run"
+          cmd_run(argv[1..])
+        when "list"
+          cmd_list
+        when "schedule"
+          cmd_schedule
+        when "new"
+          cmd_new(argv[1..])
+        when "help", "--help", "-h", nil
+          cmd_help
+        else
+          puts "Unknown command: #{argv.first}"
+          cmd_help
+          exit 1
+        end
+      end
+
+      def cmd_run(args)
+        name = args.first
+        unless name
+          puts "Usage: askr run <agent-name> [prompt]"
+          exit 1
+        end
+
+        prompt = args[1..]&.join(" ") || ""
+
+        begin
+          agent = Ask::Agent.new(name)
+
+          if prompt.empty?
+            puts "Starting interactive session with #{name}..."
+            puts "Type your message (Ctrl+D to exit):"
+            while (input = $stdin.gets)
+              response = agent.run(input.strip)
+              puts response
+              puts "---"
+            end
+          else
+            response = agent.run(prompt)
+            puts response
+          end
+        rescue Ask::UnknownAgent => e
+          puts e.message
+          exit 1
+        rescue => e
+          puts "Error: #{e.message}"
+          exit 1
+        end
+      end
+
+      def cmd_list
+        defs = Ask::Agent.definitions
+        if defs.empty?
+          puts "No agents found. Define one in agents/<name>/agent.rb or app/agents/<name>/agent.rb."
+          return
+        end
+
+        puts "Discovered agents:"
+        defs.each do |name, (klass, dir)|
+          config = klass._config
+          model = config[:model] || "(default)"
+          schedule = config[:schedule]
+          has_instructions = klass.instructions_path ? "yes" : "no"
+          tools = config[:tools].any? ? config[:tools].join(", ") : "(none)"
+
+          puts "  #{name}"
+          puts "    model:       #{model}"
+          puts "    tools:       #{tools}"
+          puts "    instructions: #{has_instructions}"
+          puts "    schedule:    #{schedule || "(none)"}" if schedule
+          puts "    directory:   #{dir}"
+        end
+      end
+
+      def cmd_schedule
+        defs = Ask::Agent.definitions
+        scheduled = defs.select { |_name, (klass, _dir)| klass._config[:schedule] }
+
+        if scheduled.empty?
+          puts "No scheduled agents found."
+          return
+        end
+
+        scheduled.each do |name, (klass, _dir)|
+          schedule = klass._config[:schedule]
+          puts "Scheduling #{name} (#{schedule})..."
+          Ask::Agent.new(name)
+        end
+
+        Ask::Agent::Scheduler.start
+        puts "Scheduler started. Running #{scheduled.length} task(s)."
+        puts "Press Ctrl+C to stop."
+
+        loop do
+          sleep 1
+        rescue Interrupt
+          puts "\nShutting down..."
+          Ask::Agent::Scheduler.stop
+          exit 0
+        end
+      end
+
+      def cmd_new(args)
+        name = args.first
+        unless name
+          puts "Usage: askr new <agent-name>"
+          exit 1
+        end
+
+        dir = File.join(Dir.pwd, "agents", name)
+        if File.exist?(dir)
+          puts "Directory already exists: #{dir}"
+          exit 1
+        end
+
+        FileUtils.mkdir_p(dir)
+
+        File.write(File.join(dir, "agent.rb"), <<~RUBY)
+          # frozen_string_literal: true
+
+          class #{camelize(name)} < Ask::Agent::Definition
+            model "gpt-4o"
+            tools :bash, :read, :grep
+          end
+        RUBY
+
+        File.write(File.join(dir, "instructions.md"), <<~MARKDOWN)
+          # #{name}
+
+          You are a helpful AI agent. Your goal is to assist the user with their tasks.
+
+          ## Guidelines
+
+          - Be concise and accurate
+          - Use the available tools when needed
+          - Ask for clarification if instructions are ambiguous
+        MARKDOWN
+
+        puts "Created agent: #{dir}"
+        puts ""
+        puts "Run it:  askr run #{name}"
+      end
+
+      def cmd_help
+        puts <<~HELP
+          Usage: askr <command> [options]
+
+          Commands:
+            run <name> [prompt]    Run an agent with an optional prompt
+            list                   List all discovered agents
+            schedule               Start the scheduler for all scheduled agents
+            new <name>             Scaffold a new agent directory
+            help                   Show this help
+
+          Examples:
+            askr list
+            askr run health_check
+            askr run health_check "Check the server status"
+            askr new deploy_bot
+            askr schedule
+
+          Agent directories are discovered from:
+            ./agents/<name>/agent.rb
+            ./app/agents/<name>/agent.rb
+        HELP
+      end
+
+      def camelize(str)
+        str.split(/[_-]/).map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/ask/agent/definition.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # Declarative agent definition backed by a file convention.
+    #
+    # Subclass +Definition+ inside an +agent.rb+ file under +agents/<name>/+
+    # or +app/agents/<name>/+. The directory name becomes the agent name.
+    # Instructions load automatically from a sibling +instructions.md+.
+    #
+    # @example +agents/health_check/agent.rb+
+    #   class HealthCheckAgent < Ask::Agent::Definition
+    #     model "gpt-4o"
+    #     tools :bash, :read, :grep
+    #     schedule "every 5 minutes"
+    #   end
+    #
+    #   # agents/health_check/instructions.md is auto-loaded
+    #
+    # @example Using from Ruby
+    #   agent = Ask::Agent.new("health_check")
+    #   agent.run("Check server health")
+    class Definition
+      @subclasses = []
+
+      class << self
+        # All subclasses that have been loaded, in definition order.
+        attr_reader :subclasses
+
+        def inherited(subclass)
+          @subclasses << subclass
+          subclass.instance_variable_set(:@_config, { tools: [] })
+
+          # Auto-detect the directory from the file where this class is defined
+          # caller(1) is the file containing the `class ... < Definition` line
+          path = caller(1)&.first&.sub(/:.*/, "")  # strip line number
+          if path && File.basename(path) == "agent.rb"
+            subclass._config[:dir] = File.dirname(path)
+          end
+
+          super
+        end
+
+        # @return [Hash] the raw config hash for this definition
+        def _config
+          @_config ||= { tools: [] }
+        end
+
+        # Set or get the model identifier.
+        def model(value = :__no_value__)
+          if value == :__no_value__
+            _config[:model]
+          else
+            _config[:model] = value
+          end
+        end
+
+        # Set tool symbols or classes.
+        def tools(*values)
+          if values.any?
+            _config[:tools] = values
+          else
+            _config[:tools]
+          end
+        end
+
+        # Set a cron or interval schedule for recurring runs.
+        def schedule(value = :__no_value__)
+          if value == :__no_value__
+            _config[:schedule]
+          else
+            _config[:schedule] = value
+          end
+        end
+
+        # Path to instructions.md relative to this definition's directory.
+        # Returns nil if no instructions file exists.
+        def instructions_path
+          dir = _config[:dir]
+          return nil unless dir
+
+          path = File.join(dir, "instructions.md")
+          File.exist?(path) ? path : nil
+        end
+
+        # Contents of the instructions.md file, or nil.
+        def instructions_content
+          path = instructions_path
+          path ? File.read(path) : nil
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/loop.rb

@@ -43,34 +43,56 @@ module Ask
         event_emitter.emit(Events::MessageEnd.new(tool_calls: response.tool_call?))
         @turn_count += 1
 
-        unless response.tool_call?
+        # Check if there are any tool calls (user-executed or provider-executed)
+        has_tool_calls = response.tool_call? || (response.tool_results&.any? == true)
+
+        unless has_tool_calls
           @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
+        provider_results = response.tool_results || {}
+        all_tool_results = []
+
+        # Add provider-executed tool results directly to conversation
+        provider_results.each do |id, result|
+          chat.add_message(role: :tool, content: result[:message].to_s, tool_call_id: id)
+          all_tool_results << {
+            tool_name: result[:tool_name] || id,
+            message: result[:message].to_s,
+            status: result[:status] || "success",
+            provider_executed: true
+          }
+        end
+
+        # Determine which tool calls still need local execution
+        user_tool_calls = response.tool_calls.reject { |id, _| provider_results.key?(id) }
+
+        if user_tool_calls.any?
+          # Execute user tool calls locally
+          user_results = tool_executor.execute_parallel(
+            user_tool_calls, tools, hooks, event_emitter, ToolAbortController.new
+          ) do |tool_call_id, result|
+            tc = user_tool_calls[tool_call_id]
+            chat.add_message(role: :tool, content: result[:message].to_s, tool_call_id: tool_call_id) if tc
+          end
+          all_tool_results.concat(user_results)
         end
 
         # Check loop detection
-        if loop_detected?(tool_results)
-          raise LoopDetected, tool_results.last[:tool_name]
+        if loop_detected?(all_tool_results)
+          raise LoopDetected, all_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("; ")
+          summary = all_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,
+          tool_results: all_tool_results,
           turn_number: @turn_count,
           input_tokens: @last_input_tokens,
           output_tokens: @last_output_tokens,

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.6.1"
+    VERSION = "0.8.0"
   end
 end

data/lib/ask/agent.rb

@@ -18,6 +18,8 @@ module Ask
     class CompactionFailed < Error; end
     class SessionNotPersisted < Error; end
 
+    class UnknownAgent < Error; end
+
     module Extensions
       autoload :PermissionGate, "ask/agent/extensions/permission_gate"
       autoload :RateLimiter, "ask/agent/extensions/rate_limiter"
@@ -40,19 +42,167 @@ module Ask
       autoload :ExtractJson, "ask/agent/stream_transforms/extract_json"
     end
 
+    @registry = {}
+    @discovered = false
+    @shared_tools = {}
+
     class << self
-      def configuration
-        @configuration ||= Configuration.new
+      # All discovered agent definitions, keyed by name.
+      # Triggers discovery on first call.
+      # @return [Hash<String, Array(Class, String)>] name → [Definition subclass, directory path]
+      def definitions
+        discover!
+        @registry.dup
+      end
+
+      # Create a new agent session from a named definition.
+      #
+      # @param name [String, Symbol] the agent name (directory name under +agents/+)
+      # @return [Session] a configured, ready-to-run session
+      def new(name)
+        discover!
+        entry = @registry[name.to_s]
+        raise UnknownAgent, "Unknown agent: #{name.inspect}. Searched agents/ and app/agents/." unless entry
+
+        klass, dir = entry
+        build_session_from_definition(klass, dir)
       end
 
-      def configure
-        yield configuration
+      # Force re-discovery of agent definitions.
+      def rediscover!
+        @discovered = false
+        @registry = {}
+        discover!
       end
 
-      def load_extensions
-        Dir[File.expand_path("agent/extensions/*.rb", __dir__)].each { |f| require f }
-      rescue Errno::ENOENT
+      # Paths where agent directories are discovered.
+      def default_agent_paths
+        [
+          File.join(Dir.pwd, "agents"),
+          File.join(Dir.pwd, "app", "agents")
+        ]
       end
+
+      # Resolve a tool symbol to a tool class.
+      # Checks the shared tools directory first, then falls back to the
+      # global tool registry from ask-tools.
+      def resolve_tool_symbol(symbol)
+        @shared_tools[symbol.to_s] || begin
+          Ask::Tools[symbol.to_s]
+        rescue StandardError
+          nil
+        end
+      end
+
+      private
+
+      def discover!
+        return if @discovered
+        @discovered = true
+
+        paths = default_agent_paths
+        paths.each do |base|
+          next unless File.directory?(base)
+
+          # Discover shared tools
+          discover_shared_tools(base)
+
+          # Discover agent directories
+          Dir["#{base}/*/agent.rb"].sort.each do |file|
+            dir = File.dirname(file)
+            name = File.basename(dir)
+            next if name == "shared"
+
+            require file
+
+            # Find the Definition subclass whose directory matches
+            match = Definition.subclasses.find { |klass|
+              klass._config[:dir] == dir
+            }
+
+            if match
+              @registry[name] = [match, dir]
+            end
+          end
+        end
+      end
+
+      def discover_shared_tools(base)
+        shared_tools_dir = File.join(base, "shared", "tools")
+        return unless File.directory?(shared_tools_dir)
+
+        Dir["#{shared_tools_dir}/*.rb"].sort.each do |file|
+          tool_name = File.basename(file, ".rb")
+          require file
+
+          # Find the Ask::Tool subclass that was just loaded
+          # (it registered itself in Ask::Tools on require)
+          @shared_tools[tool_name] = tool_name
+        end
+      end
+
+      def build_session_from_definition(klass, dir)
+        config = klass._config
+        session_opts = { model: config[:model] || Ask::Agent.configuration.default_model }
+
+        # Resolve tools
+        tools = resolve_definition_tools(config[:tools], dir)
+        session_opts[:tools] = tools if tools.any?
+
+        # Load instructions
+        prompt = klass.instructions_content
+        session_opts[:system_prompt] = prompt if prompt
+
+        # Apply schedule if defined
+        schedule = config[:schedule]
+        if schedule
+          task_block = ->(sess = nil) {
+            agent = build_session_from_definition(klass, dir)
+            agent.run("")
+          }
+          Ask::Agent.configuration.scheduler.every(schedule, name: File.basename(dir), &task_block)
+        end
+
+        Session.new(**session_opts)
+      end
+
+      def resolve_definition_tools(tool_specs, dir)
+        tools = []
+        tool_specs.each do |spec|
+          case spec
+          when Symbol, String
+            name = spec.to_s
+            # Try per-agent tools directory
+            agent_tool_path = File.join(dir, "tools", "#{name}.rb")
+            if File.exist?(agent_tool_path)
+              require agent_tool_path
+            end
+
+            resolved = resolve_tool_symbol(name)
+            if resolved
+              tool_class = resolved.is_a?(Class) ? resolved : Ask::Tools[name]
+              tools << tool_class if tool_class
+            end
+          when Class
+            tools << spec
+          end
+        end
+        tools
+      end
+    end
+
+    # Register the global config
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield configuration
+    end
+
+    def self.load_extensions
+      Dir[File.expand_path("agent/extensions/*.rb", __dir__)].each { |f| require f }
+    rescue Errno::ENOENT
     end
   end
 end
@@ -70,10 +220,12 @@ require_relative "agent/compactor"
 require_relative "agent/hooks"
 require_relative "agent/configuration"
 require_relative "agent/meta_agent"
-require_relative "agent/scheduler"
 require_relative "agent/persistence/base"
 require_relative "agent/persistence/in_memory"
 require_relative "agent/skills/load_skill_tool"
+require_relative "agent/scheduler"
+require_relative "agent/definition"
+require_relative "agent/cli"
 
 # Test helpers (loaded on demand)
 autoload :Test, "ask/agent/test"

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Kaka Ruto
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -139,18 +139,22 @@ description: Agent loop, session management, tool execution, context compaction,
   and extensions.
 email:
 - kaka@myrrlabs.com
-executables: []
+executables:
+- askr
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/askr
 - lib/ask-agent.rb
 - lib/ask/agent.rb
 - lib/ask/agent/chat.rb
+- lib/ask/agent/cli.rb
 - lib/ask/agent/compactor.rb
 - lib/ask/agent/configuration.rb
+- lib/ask/agent/definition.rb
 - lib/ask/agent/events.rb
 - lib/ask/agent/extensions/audit_log.rb
 - lib/ask/agent/extensions/permission_gate.rb