ask-agent 0.23.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf7561a6eebc134d4e84ba829e637638a783eb7dd425c1b1c24d2d879e5ff47e
-  data.tar.gz: 73cdf03eec1b27f3e50cbfa28399bdf17994ea1b5925be36ce463ebf48c6669d
+  metadata.gz: e5268e3474f109d7471749692a535a89b266e5a9d10c20499a565087500eaee8
+  data.tar.gz: 24fc0068d51f1eedc2e0d6f427234db468db375e915a4383533086993dab8b5d
 SHA512:
-  metadata.gz: 37b261bba11ac89e4051b2f631305ed6741ae8ba6a18f0973a2fa7a04416d3dd84d2ca9e4517d01f4776a21fbf143125a51bcceb74b67ce361d9c4ea35e15279
-  data.tar.gz: bc3051e56b9b68a003da46e1ee4c4ec10265239bfc2482c6cc335caf510f099256e1487526ead9277687004a0bb4c68926efb9f51db338b103f69188f21ed60a
+  metadata.gz: 8dddca135834b42108d217fc09a121a4fc4fd4ad44da326849b9654f30ba393bc115b44a3bc756433a7cbb8bd1b729d02dc246feb540e6f0ff39dc2aff1e56ad
+  data.tar.gz: 5cde0691f9aa8bd6723c20344211c50cc18e15ffdf392d97710896d4752b8343c583faab5de7e4156e261049676dbe06e2136162a8d10d1b48e9ae3e174f7786

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.24.0] — 2026-07-30
+
+### Changed
+
+- **Agent class convention is now `<Name>::Agent`, not `<Name>Agent`.**
+  `agents/health_check/agent.rb` defines `module HealthCheck; class Agent <
+  Ask::Agent::Definition` — matching the ecosystem's `Xxx::Workflow` /
+  `Xxx::Create` naming. Directory-based discovery is unchanged.
+
+### Fixed
+
+- **Discovery re-points definitions when the class constant is re-opened.**
+  Requiring an `agent.rb` from a second location (same agent name, e.g. test
+  fixtures) re-opens the existing `<Name>::Agent` constant instead of
+  redefining it, so `inherited` never fires and the definition kept its old
+  directory. Discovery now falls back to matching by conventional class name
+  and re-points `_config[:dir]` at the current directory.
+
 ## [0.23.0] — 2026-07-30
 
 ### Added

data/README.md

@@ -213,6 +213,42 @@ c.middleware.use :model_fallback,
   eligible_errors: [Ask::RateLimitError, Ask::ServerError]
 ```
 
+## Agents
+
+Declarative agents follow a file convention. Each agent lives in a
+directory under `agents/` (or `app/agents/` in Rails); the directory
+name is the agent name, the file `agent.rb` defines the agent as a
+`<Name>::Agent < Ask::Agent::Definition` subclass, and a sibling
+`instructions.md` is auto-loaded as the system prompt.
+
+```
+agents/
+└── health_check/          # agent name: "health_check"
+    ├── agent.rb           # module HealthCheck; class Agent < Ask::Agent::Definition
+    ├── instructions.md    # auto-loaded system prompt
+    └── tools/             # per-agent tools (referenced with `tools :name`)
+```
+
+```ruby
+# agents/health_check/agent.rb
+module HealthCheck
+  class Agent < Ask::Agent::Definition
+    model "gpt-4o"
+    tools :bash, :read, :grep
+  end
+end
+```
+
+Run it by name:
+
+```ruby
+agent = Ask::Agent.new("health_check")
+response = agent.run("Check server health")
+```
+
+Shared tools for all agents go in `agents/shared/tools/`. Per-agent
+skills go in `agents/<name>/skills/`, shared skills in `agents/shared/skills/`.
+
 ## Configuration
 
 ```ruby

data/lib/ask/agent/definition.rb

@@ -9,10 +9,12 @@ module Ask
     # 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"
+    #   module HealthCheck
+    #     class Agent < Ask::Agent::Definition
+    #       model "gpt-4o"
+    #       tools :bash, :read, :grep
+    #       schedule "every 5 minutes"
+    #     end
     #   end
     #
     #   # agents/health_check/instructions.md is auto-loaded
@@ -25,10 +27,18 @@ module Ask
 
       class << self
         # All subclasses that have been loaded, in definition order.
-        attr_reader :subclasses
+        # Reads from Definition itself so intermediate base classes
+        # (e.g. ApplicationAgent) report the same registry.
+        def subclasses
+          Definition.instance_variable_get(:@subclasses) || []
+        end
 
         def inherited(subclass)
-          @subclasses << subclass
+          # Track on Definition itself, not self — inherited fires with the
+          # immediate parent as receiver, so an intermediate base class
+          # (e.g. an ApplicationAgent in a Rails app) would otherwise have a
+          # nil @subclasses ivar.
+          Definition.subclasses << subclass
           subclass.instance_variable_set(:@_config, { tools: [] })
 
           # Auto-detect the directory from the file where this class is defined

data/lib/ask/agent/version.rb

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

data/lib/ask/agent.rb

@@ -117,10 +117,13 @@ module Ask
 
             require file
 
-            # Find the Definition subclass whose directory matches
-            match = Definition.subclasses.find { |klass|
-              klass._config[:dir] == dir
-            }
+            # Find the Definition subclass whose directory matches.
+            # Falls back to matching by conventional class name
+            # (<Name>::Agent) for agents re-opened from another location
+            # (e.g. same-named fixtures across test runs) — Ruby reopens
+            # an existing constant instead of redefining it, so the
+            # inherited hook doesn't fire a second time.
+            match = find_definition_for(dir, name)
 
             if match
               @registry[name] = [match, dir]
@@ -129,6 +132,22 @@ module Ask
         end
       end
 
+      # Find the Definition subclass for an agent directory.
+      #
+      # First tries an exact directory match (fresh definitions). When the
+      # class constant already exists — loaded from a different directory
+      # with the same agent name — re-points it at this directory so the
+      # returned definition is always current.
+      def find_definition_for(dir, name)
+        match = Definition.subclasses.find { |klass| klass._config[:dir] == dir }
+        return match if match
+
+        convention_name = name.split("_").map(&:capitalize).join + "::Agent"
+        match = Definition.subclasses.find { |klass| klass.name == convention_name }
+        match&._config&.[]=(:dir, dir)
+        match
+      end
+
       def discover_shared_tools(base)
         shared_tools_dir = File.join(base, "shared", "tools")
         return unless File.directory?(shared_tools_dir)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Kaka Ruto