ask-agent 0.40.18 → 0.40.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e97d8067438c6de7e631a5837fc93355b9db6a2b94fd143d0e4421b59c9ec177
-  data.tar.gz: 4853729a9c4fa158bca58146b8b9e8305b6264cb1a12fb2b5750d8a2bcc79d03
+  metadata.gz: 46ea77e0ac0feca360164604367729e05f15e22212f479c59ad1954da5e5e924
+  data.tar.gz: 5a1e0198d2e4d9faf7831bd1c7f8520a82a01c7fff46a9a94512a60a6d285409
 SHA512:
-  metadata.gz: 75def0a97595224d12c77fdbfadb875608c11afc0247b10e37058de1d1004f37addc1eb1ccbe64dd1c28a0a0f712ae024efe42d5372341a4876b6e8b32f5b0eb
-  data.tar.gz: 526100d9bc12da6404419c2ab21b64b73f735e0b5c773ced77816eb231c23f0816cce4a9b344108a542fc3b50f8b84781bb81244dc6e991c89435e26e0ef4920
+  metadata.gz: d195e1e86df0f281de603cdd607d0b2d88bbbc3d07f4c46b5dbb81235fd102d7f4a19781e625b8ddd8c304babb47eaf60fa894c6513b5e944f493b0e4928c74f
+  data.tar.gz: c4289b1c74e4ee05de9ffe2c0c266e46599e49c546b0c22c23ea76258a23e291dd5804e3d5cdd0d514375540fc22d7732a920de1e6d303f7dfde0fcbc04ca883

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/version.rb

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

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.18
+  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