ask-agent 0.40.17 → 0.40.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12c8a3be5e9171a9dea21e3a8107c7953d7772ddb2c6fd82d23805f54557f5dc
-  data.tar.gz: cb751bf89f94b3206f1900d9d33f738a8f248dc9c61552867cf1349a3ffd8a6d
+  metadata.gz: 46ea77e0ac0feca360164604367729e05f15e22212f479c59ad1954da5e5e924
+  data.tar.gz: 5a1e0198d2e4d9faf7831bd1c7f8520a82a01c7fff46a9a94512a60a6d285409
 SHA512:
-  metadata.gz: b046b9f9bef45c3ed959acf97a2b3c3afa6921f240ac4a3ac6d59204424122ef8fd3e6e8f6614ebe695918c043b3de8fb655a92783e52eed72f255791e20c1eb
-  data.tar.gz: 3bf7b88e021f181cae2271ac9311976de44d73b5433aa4241347ad3c9c61d96056bc31e13ac73589a9e871e79d9210d5a3d1cd8577767c777a672558ad4b2f73
+  metadata.gz: d195e1e86df0f281de603cdd607d0b2d88bbbc3d07f4c46b5dbb81235fd102d7f4a19781e625b8ddd8c304babb47eaf60fa894c6513b5e944f493b0e4928c74f
+  data.tar.gz: c4289b1c74e4ee05de9ffe2c0c266e46599e49c546b0c22c23ea76258a23e291dd5804e3d5cdd0d514375540fc22d7732a920de1e6d303f7dfde0fcbc04ca883

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.40.17] — 2026-09-18
+
+### Added
+
+- **`decision_provider` — a session can take a decision provider, and its
+  tool calls get judged.** Set it globally
+  (`Ask::Agent.configure { |c| c.decision_provider = :typesafe }`) or per
+  session. `Ask::Decisions::AgentAdapter` then wires a gate in front of every
+  tool call and an output judge behind it; ask-agent itself never requires
+  ask-decisions, and with the setting unset nothing changes at all.
+
+### Changed
+
+- Requires `ask-core >= 0.12.0` for the decision vocabulary.
+
+
 ## [0.40.10] — 2026-09-05
 
 ### Fixed

data/lib/ask/agent/cli.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 module Ask
   module Agent
     module CLI
       module_function
 
       def run(argv)
+        auto_sync_skills
         case argv.first
         when "run"
           cmd_run(argv[1..])
@@ -162,13 +165,21 @@ module Ask
           cmd_skills_show(args[1])
         when "search"
           cmd_skills_search(args[1])
+        when "install"
+          cmd_skills_install(args[1..])
+        when "uninstall"
+          cmd_skills_uninstall(args[1..])
         else
-          puts "Usage: askr skills <list|show|search>"
+          puts "Usage: askr skills <list|show|search|install|uninstall>"
           puts ""
           puts "Commands:"
           puts "  list                  List all discovered skills"
           puts "  show <name>           Show skill details and sibling files"
           puts "  search <query>        Search skills by name, description, or tags"
+          puts "  install [--global]    Install ask-agent skill to ~/.agents/skills/ (default)"
+          puts "  install --local       Install to .agents/skills/ in current directory"
+          puts "  uninstall [--global]  Remove installed skill"
+          puts "  uninstall --local     Remove locally installed skill"
         end
       end
 
@@ -259,6 +270,112 @@ module Ask
         end
       end
 
+      SKILL_NAME = "agent.build_agents"
+      SKILL_SOURCE_REL = "ask/skills/agent.build_agents/SKILL.md"
+
+      # Keep installed copies in sync after `gem update ask-agent`.
+      # Only touches copies created by `askr skills install` (identified
+      # by the marker file). Failures are swallowed.
+      def auto_sync_skills
+        skill_candidates.each do |dest|
+          next unless File.file?(dest)
+          next unless skill_managed?(dest)
+          skill_sync_copy(dest)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def cmd_skills_install(args)
+        opts = parse_skill_flags(args)
+        dest = skill_target_dir(opts)
+        source = skill_bundled_path
+        unless File.file?(source)
+          puts "Bundled skill not found at #{source} — reinstall ask-agent"
+          exit 1
+        end
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(source, dest)
+        skill_stamp(dest)
+        puts "Installed #{SKILL_NAME} skill -> #{dest}"
+        0
+      end
+
+      def cmd_skills_uninstall(args)
+        opts = parse_skill_flags(args)
+        dest = skill_target_dir(opts)
+        if File.file?(dest)
+          FileUtils.rm(dest)
+          FileUtils.rm_f(skill_managed_marker(dest))
+          puts "Removed #{dest}"
+        else
+          puts "Not installed at #{dest} (nothing to do)"
+        end
+        0
+      end
+
+      def skill_target_dir(opts)
+        if opts[:dir]
+          File.expand_path(File.join(opts[:dir], SKILL_NAME, "SKILL.md"))
+        elsif opts[:local]
+          File.join(Dir.pwd, ".agents", "skills", SKILL_NAME, "SKILL.md")
+        else
+          File.expand_path("~/.agents/skills/#{SKILL_NAME}/SKILL.md")
+        end
+      end
+
+      def skill_bundled_path
+        File.expand_path("../../#{SKILL_SOURCE_REL}", __dir__)
+      end
+
+      def skill_managed_marker(dest)
+        File.join(File.dirname(dest), ".ask-agent-managed")
+      end
+
+      def skill_managed?(dest)
+        File.file?(skill_managed_marker(dest))
+      end
+
+      def skill_stamp(dest)
+        File.write(skill_managed_marker(dest), "managed by askr skills install; safe to auto-update\n")
+      rescue StandardError
+        nil
+      end
+
+      def skill_candidates
+        [
+          File.expand_path("~/.agents/skills/#{SKILL_NAME}/SKILL.md"),
+          File.join(Dir.pwd, ".agents", "skills", SKILL_NAME, "SKILL.md")
+        ]
+      end
+
+      def skill_sync_copy(dest)
+        source = skill_bundled_path
+        FileUtils.cp(source, dest) if File.exist?(source) && File.read(source) != File.read(dest)
+        skill_stamp(dest)
+      rescue StandardError
+        nil
+      end
+
+      def parse_skill_flags(args)
+        opts = {}
+        args.each do |arg|
+          case arg
+          when "--local" then opts[:local] = true
+          when "--global" then nil # default
+          when "--dir"
+            # next arg is the path; handled by shifting in the caller
+          when /\A--dir=(.+)/ then opts[:dir] = $1
+          when "--help", "-h"
+            puts "Usage: askr skills install [--global] [--local] [--dir <path>]"
+            puts "       askr skills uninstall [--global] [--local] [--dir <path>]"
+            exit 0
+          end
+        end
+        opts
+      end
+
       def cmd_help
         puts <<~HELP
           Usage: askr <command> [options]

data/lib/ask/agent/session.rb

@@ -23,6 +23,58 @@ module Ask
       # @return [Ask::Decisions::AgentAdapter, nil] decision adapter (when decision_provider is set)
       attr_reader :decision_adapter
 
+      # Build a Session from a discovered Definition class and directory.
+      #
+      # This is the shared implementation used by both Ask::Agent.new(name)
+      # and Session.new(name:). It resolves the definition's config, tools,
+      # and instructions, then applies any caller-supplied overrides.
+      #
+      # @param klass [Class] the Definition subclass
+      # @param dir [String] the agent directory path
+      # @param opts [Hash] runtime overrides (model, provider, tools, system_prompt, etc.)
+      # @return [Session]
+      def self.build_from_definition(klass, dir, opts = {})
+        config = klass._config
+        session_opts = { model: config[:model] || Ask::Agent.configuration.default_model }
+
+        # Pass optional config
+        session_opts[:provider] = config[:provider] if config[:provider]
+        session_opts[:max_turns] = config[:max_turns] if config[:max_turns]
+        session_opts[:parallel_tools] = config[:parallel_tools] if config.key?(:parallel_tools)
+        session_opts[:skills_disclosure] = config[:skills_disclosure] if config.key?(:skills_disclosure)
+
+        # Pass arbitrary session options
+        if config[:options]
+          session_opts.merge!(config[:options])
+        end
+
+        # Pass agent directory for per-agent skills discovery
+        session_opts[:agent_dir] = dir
+
+        # 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_from_definition(klass, dir)
+            agent.run("")
+          }
+          Ask::Agent.configuration.scheduler.every(schedule, name: File.basename(dir), &task_block)
+        end
+
+        # Caller-supplied runtime options win over the definition's config.
+        session_opts.merge!(opts) unless opts.empty?
+
+        new(**session_opts)
+      end
+
       def initialize(model:, tools: [], max_turns: 25, max_tool_retries: 3,
                      compactor: nil, hooks: {}, state: nil, persistence: nil,
                      id: nil, system_prompt: nil, parallel_tools: true,
@@ -1148,6 +1200,34 @@ end
 
       # Recursively convert string keys to symbol keys in hashes.
       # Needed when loading session data that was serialized through JSON.
+      # Resolve tool specs (symbols, strings, or classes) from a Definition
+      # into instantiated tool objects. Symbols are looked up in the agent's
+      # per-agent tools/ directory first, then shared tools, then the global
+      # Ask::Tools registry.
+      def self.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 = Ask::Agent.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
+
       def self.deep_symbolize_keys(obj)
         case obj
         when Hash

data/lib/ask/agent/sub_agent.rb

@@ -161,7 +161,7 @@ module Ask
         @provider = config[:provider]
 
         # Resolve tools from definition
-        resolved_tools = Ask::Agent.__send__(:resolve_definition_tools, config[:tools] || [], dir)
+        resolved_tools = Ask::Agent::Session.resolve_definition_tools(config[:tools] || [], dir)
         @tools = resolved_tools.map { |t| t.is_a?(Class) ? t.new : t }
 
         # Load instructions from definition

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.40.17"
+    VERSION = "0.40.19"
   end
 end

data/lib/ask/agent.rb

@@ -94,7 +94,7 @@ module Ask
         raise UnknownAgent, "Unknown agent: #{name.inspect}. Searched agents/ and app/agents/." unless entry
 
         klass, dir = entry
-        build_session_from_definition(klass, dir, opts)
+        Session.build_from_definition(klass, dir, opts)
       end
 
       # Force re-discovery of agent definitions.
@@ -188,73 +188,6 @@ module Ask
           @shared_tools[tool_name] = tool_name
         end
       end
-
-      def build_session_from_definition(klass, dir, opts = {})
-        config = klass._config
-        session_opts = { model: config[:model] || Ask::Agent.configuration.default_model }
-
-        # Pass optional config
-        session_opts[:provider] = config[:provider] if config[:provider]
-        session_opts[:max_turns] = config[:max_turns] if config[:max_turns]
-        session_opts[:parallel_tools] = config[:parallel_tools] if config.key?(:parallel_tools)
-        session_opts[:skills_disclosure] = config[:skills_disclosure] if config.key?(:skills_disclosure)
-
-        # Pass arbitrary session options
-        if config[:options]
-          session_opts.merge!(config[:options])
-        end
-
-        # Pass agent directory for per-agent skills discovery
-        session_opts[:agent_dir] = dir
-
-        # 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
-
-        # Caller-supplied runtime options (model/provider/api_key/api_base/...)
-        # win over the definition's config.
-        session_opts.merge!(opts) unless opts.empty?
-
-        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
@@ -336,12 +269,24 @@ end
 #   Ask.chat("Tell me about X", model: "gpt-4o")
 #   Ask.chat("Stream this") { |chunk| puts chunk.content }
 #
+# With a named definition:
+#
+#   Ask.chat("Check health", name: "health_check")
+#   Ask.chat("Check health", name: "health_check", model: "claude-sonnet-4")
+#
 module Ask
-  def self.chat(message, model: nil, system_prompt: nil, &block)
-    session = Agent::Session.new(
-      model: model || Agent.configuration.default_model,
-      system_prompt: system_prompt
-    )
+  def self.chat(message, name: nil, model: nil, system_prompt: nil, &block)
+    session = if name
+      overrides = {}
+      overrides[:model] = model if model
+      overrides[:system_prompt] = system_prompt if system_prompt
+      Agent.new(name, **overrides)
+    else
+      Agent::Session.new(
+        model: model || Agent.configuration.default_model,
+        system_prompt: system_prompt
+      )
+    end
     if block
       session.run(message, &block)
     else

data/lib/ask/skills/agent.build_agents/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: agent.build_agents
+description: Build AI agents with ask-rb — define agents, register tools, configure sessions, and wire up the agent loop. Use when creating new agents, adding tools to existing agents, debugging agent behavior, or setting up agent definitions.
+tags: agents, tools, sessions, ask-rb, development
+---
+
+# Building Agents with ask-rb
+
+Step-by-step methodology for creating AI agents using the ask-rb ecosystem.
+
+## Agent Definition (Convention-Based)
+
+Every agent lives in a directory under `agents/` or `app/agents/`. The directory name is the agent name.
+
+### Directory Structure
+
+```
+agents/
+├── health_check/
+│   ├── agent.rb           → Definition subclass (required)
+│   ├── instructions.md    → System prompt (auto-loaded)
+│   ├── tools/             → Per-agent tools (optional)
+│   │   └── disk_check.rb
+│   └── skills/            → Per-agent skills (optional)
+│       └── nginx_debug/SKILL.md
+├── shared/
+│   ├── tools/             → Shared across all agents
+│   │   └── notify.rb
+│   └── skills/            → Shared skills
+└── daily_report/
+    ├── agent.rb
+    └── instructions.md
+```
+
+### Definition DSL
+
+```ruby
+# agents/health_check/agent.rb
+module HealthCheck
+  class Agent < Ask::Agent::Definition
+    model "gpt-4o"                    # required: which LLM to use
+    provider :anthropic               # optional: override provider
+    tools :bash, :read, :grep         # tool symbols or classes
+    max_turns 30                      # optional: conversation limit
+    parallel_tools true               # optional: parallel execution (default: true)
+    skills_disclosure true            # optional: load_skill tool (default: true)
+    schedule "every 5 minutes"        # optional: cron/interval
+    option :temperature, 0.7          # optional: arbitrary Session option
+  end
+end
+```
+
+### Tool Symbol Resolution
+
+Symbols (`:bash`, `:read`) are resolved in order:
+1. Per-agent tools: `agents/<name>/tools/<name>.rb`
+2. Shared tools: `agents/shared/tools/<name>.rb`
+3. Global registry: `Ask::Tools[name]` (built-in tools from ask-tools)
+
+## Session Creation (Unified API)
+
+`Session.build_from_definition` is the single source of truth. Three entry points converge on it:
+
+### From a Definition (Recommended)
+
+```ruby
+# Via Agent.new — convenience shorthand
+agent = Ask::Agent.new("health_check")
+agent.run("Check server health")
+
+# Explicit — when you have the class and directory
+session = Ask::Agent::Session.build_from_definition(
+  HealthCheck::Agent, "agents/health_check"
+)
+```
+
+### Direct (No Definition)
+
+```ruby
+session = Ask::Agent::Session.new(
+  model: "gpt-4o",
+  tools: [Ask::Tools::Bash, Ask::Tools::Read],
+  system_prompt: "You are a helpful assistant."
+)
+session.run("Hello")
+```
+
+### One-Shot Chat
+
+```ruby
+Ask.chat("Check health")
+Ask.chat("Check health", model: "claude-sonnet-4")
+Ask.chat("Check health", name: "health_check")  # from definition
+```
+
+### Overriding Definition Config
+
+Any explicit option overrides the definition's value:
+
+```ruby
+agent = Ask::Agent.new("health_check", model: "claude-sonnet-4")
+agent = Ask::Agent.new("health_check", system_prompt: "Custom prompt")
+```
+
+## Writing Tools
+
+### Tool Class
+
+```ruby
+# agents/health_check/tools/disk_check.rb
+class DiskCheck < Ask::Tool
+  description "Check disk usage on a path"
+  param :path, type: :string, desc: "Path to check", required: true
+  param :threshold, type: :integer, desc: "Warning threshold in %", default: 80
+
+  def execute(path:, threshold: 80)
+    usage = `df -h #{path} | tail -1 | awk '{print $5}'`.strip.to_i
+    if usage > threshold
+      Ask::Result.error(data: "Disk usage #{usage}% exceeds threshold #{threshold}%")
+    else
+      Ask::Result.ok(data: "Disk usage: #{usage}%")
+    end
+  end
+end
+```
+
+### Tool Registration
+
+```ruby
+# In agent.rb — symbols resolve via convention
+tools :bash, :read, :disk_check
+
+# Or pass classes directly (no file convention needed)
+tools Ask::Tools::Bash, DiskCheck
+```
+
+### Async Tools (Background Execution)
+
+```ruby
+class LongTask < Ask::Tool
+  description "Run a long-running task in the background"
+
+  def execute(task:)
+    # Return pending — the loop continues while this runs
+    Ask::Result.pending(
+      tool_call_id: current_tool_call_id,
+      message: "Task started in background"
+    )
+  end
+end
+```
+
+Complete with `session.complete_pending_tool(tool_call_id:, result:)` from a background thread.
+
+## Session Options
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `model:` | (required) | LLM model identifier |
+| `tools:` | `[]` | Tool classes or instances |
+| `system_prompt:` | `nil` | System instructions |
+| `max_turns:` | `25` | Conversation turn limit |
+| `max_tool_retries:` | `3` | Retries per failed tool call |
+| `parallel_tools:` | `true` | Execute tools concurrently |
+| `skills_disclosure:` | `true` | Include load_skill tool |
+| `state:` | `nil` | Persistence adapter |
+| `checkpoints:` | `false` | Enable fork/rollback |
+| `todos:` | `false` | Enable task list tool |
+| `plan_mode:` | `false` | Read-only research phase |
+| `memory:` | `nil` | Durable memory adapter |
+| `memory_learning:` | `false` | Auto-extract facts |
+| `evaluator:` | `nil` | Independent evaluation |
+| `reflector:` | `nil` | Self-reflection |
+| `approval:` | `nil` | Human-in-the-loop |
+| `compactor:` | `nil` | Context window management |
+| `hooks:` | `{}` | Before/after tool callbacks |
+| `telemetry:` | `true` | Error tracking |
+
+## Event System
+
+```ruby
+session.on_event do |event|
+  case event
+  when Ask::Agent::Events::TextDelta
+    print event.content
+  when Ask::Agent::Events::ToolExecutionStart
+    puts "Running #{event.name}..."
+  when Ask::Agent::Events::SessionEnd
+    puts "Done: #{event.tool_calls_made} tools, $#{event.cost}"
+  end
+end
+```
+
+## Common Patterns
+
+### Multi-Agent Coordination
+
+```ruby
+search = Ask::Agent::SubAgent.new("web_search")
+review = Ask::Agent::SubAgent.new("code_review")
+
+coordinator = Ask::Agent::Session.new(
+  model: "gpt-4o",
+  tools: [search, review, Ask::Tools::Bash]
+)
+coordinator.run("Find the latest Rails release and check our Gemfile")
+```
+
+### Persistent Sessions
+
+```ruby
+store = Ask::State::Providers::SQLite.new
+session = Ask::Agent::Session.new(
+  model: "gpt-4o",
+  tools: tools,
+  state: store,
+  checkpoints: true
+)
+
+session.run("Investigate the error")
+restored = Ask::Agent::Session.load(session.id, adapter: store)
+restored.run("What else should I check?")
+```
+
+### Scheduled Agents
+
+```ruby
+# In agent.rb:
+class HealthCheck < Ask::Agent::Definition
+  model "gpt-4o"
+  tools :bash, :read
+  schedule "every 5 minutes"
+end
+
+# Or globally:
+Ask::Agent.configure do |c|
+  c.scheduler.every "5 minutes", name: "health-check" do
+    Ask::Agent.new("health_check").run("Check server health")
+  end
+end
+Ask::Agent::Scheduler.start
+```
+
+## CLI
+
+```bash
+askr list                    # List all discovered agents
+askr run health_check        # Run an agent
+askr run health_check "..."  # Run with a prompt
+askr new deploy_bot          # Scaffold a new agent
+askr skills list             # List all discovered skills
+askr skills install          # Install ask-agent skill to ~/.agents/skills/
+askr skills uninstall        # Remove installed skill
+```
+
+## Troubleshooting
+
+- **Agent not found**: Check `agents/<name>/agent.rb` exists and the class subclasses `Ask::Agent::Definition`
+- **Tool not resolving**: Verify the tool file is in `agents/<name>/tools/` or registered in `Ask::Tools`
+- **No system prompt**: Ensure `instructions.md` exists next to `agent.rb`
+- **Skills not loading**: Check `skills_disclosure: true` (default) and the skill file follows `SKILL.md` convention

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.40.17
+  version: 0.40.19
 platform: ruby
 authors:
 - Kaka Ruto
@@ -219,6 +219,7 @@ files:
 - lib/ask/agent/tool_executor.rb
 - lib/ask/agent/tool_output_store.rb
 - lib/ask/agent/version.rb
+- lib/ask/skills/agent.build_agents/SKILL.md
 homepage: https://github.com/ask-rb/ask-agent
 licenses:
 - MIT