ask-agent 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ad6219a4374a7aeb4688533bcf7a0a68ebb166de2d96d2e9953eb6814fe5c5
-  data.tar.gz: 89e4e0413d96f90dd30d4203fa4023331663b2818a5df89c0a60a6975fb8bcb9
+  metadata.gz: 3d3eb1ad33d205f6b868c931aabf78172bc3b3d3dca0674ad67910d1ff7997a2
+  data.tar.gz: faff03efa8eba0d1594756745b9a29dcb8c2d51a362d818f7ec18904c3f9f92e
 SHA512:
-  metadata.gz: 9557223b85bc04778cd6821a9b7807818e06ac85124d95f79469db613a7a23d8e8317db5e6454517adf5b67fd68806eafc4ec145f8c3ea08d01de93d4f939a91
-  data.tar.gz: 53d3a056d6c8004bdd32536f3781bae6a0bee21bd12f1af12bc3eefab02e3f229df6109c8f5f2c6802229177aa28c27a17804bb348e93c4898adce62289222d5
+  metadata.gz: a9212d2d0730b6e5a9df227bb75c15a8491685b9243e6cf5f4f7511763e51a4b0bcc31c624f760e113c9e52d701863cf95664d67200bc54d67d7d9922932d6f6
+  data.tar.gz: 1c8664489865b480faf003c19952fc13963238e1259c9f3e7170592a31a10eca13b39cab40fa2d428274b3f3f49a405b8be817a5475b3e86fd211bcfa4c1630b

data/CHANGELOG.md

@@ -1,3 +1,45 @@
+## [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/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/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.6.1"
+    VERSION = "0.7.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.7.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