aigency 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b9b5b24d49d87f69a17cec9420b4815db4646b37d8759951e4ced8431765800
-  data.tar.gz: 04ecc1ddb1433cfcd2c18b7c3af420df7dd52a417ef6ab90a2a3de35adb2b99b
+  metadata.gz: 4fce24d7da34c83fac5e0d3ce82d8bb79c31bede2b99ddfacec3b7efa4d157e3
+  data.tar.gz: 1a36424698a8a9b4bba0a0a0cf6a14e9b4cf8318a40a166893be3e093c909f9e
 SHA512:
-  metadata.gz: 6ab68e574725ebb40bad60ff6e807e480733c91f406d75c8e45b6678e16952e0cd67dde124df13ef9036ef82437bcdae97a4182169cbc615b30116f29c89667c
-  data.tar.gz: 6a4e0866fc61258b3fee11e76baeadc72ade5d5d66b87f4d8d41ad2127ac27a50a5f7ef394d0d940e03d7cc389e567f4d7e814ebb1792ef56c125904a75c4dcc
+  metadata.gz: 9ce7989e062eb10afbb767d3e61f297ddf521f0b7c5fe0459c8021428843e6b05069db1ae88afbda7c29ab4ea0ca9f9f277b7472393f085f87dc5b36866cd786
+  data.tar.gz: 9a7a1efaad6467200964715b3db7920b52cc1cc39c7292fd8a52a2b4d4d023b16502ea511ee6824664970fecbdab19b2529dd95a2a5d0a8dfc49f9c53a5e062d

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## 0.4.0 - October 21, 2026
+- Config file directory
+- Add openssh to sandbox
+- Sandbox configuration
+- Tempdir tools
+- Aigent plugin
+- Proxy environment variables
+- apk update && apk upgrade
+- Plugins add rake files
+- Aigent setup in README
+- Rearrange sandbox scaffold
+- Add bin/aigent to aigent directory
+- Fix grep spec for BusyBox
+- CurrentTime tool
+- Dockerfile packages and mise setup
+- Instructions subcommand
+- Aigent#stream errors write to error.log
+- Aigent stream command
+- Remove adduser recommendation
+- Clarify Docker requirement
+- Plugin shells
+- Tempdir file size management
+- CopyTempdirFile tool
+- Aigent plugin setup
+- Update chat calls for RubyLLM 2.0
+- Use the chat completions protocol
+
+## 0.3.0 - October 9, 2026
+- New plugin architecture
+- Workspace and Sandbox plugins
+
 ## 0.2.0 - October 2, 2026
 - Log token usage
 - Stale code

data/README.md

@@ -2,6 +2,13 @@
 
 A framework for creating AI agents with RubyLLM.
 
+## Requirements
+
+- Ruby 3.2+
+- Docker 29+ (required for sandbox)
+
+(Note: Aigency is not tested on Windows. Some features are known to be Windows-incompatible.)
+
 ## Installation
 
 Install the gem from the command line:
@@ -20,28 +27,20 @@ gem 'aigency'
 
 ### Creating a New Aigent
 
-The recommended way to create an aigent is to give it a dedicated system user.
-
-```bash
-useradd aigent_user
-sudo su - aigent_user
-```
-
-Once you're logged in as the aigent user, create the aigent directory:
-
 ```bash
 aigency enlist
 cd aigent
 bundle install
 rake setup
+cp .env.example .env
 ```
 
-The bare minimum configuration you need to do is setting `openai_api_base` and `openai_api_key` in `config/aigent.yml`.
+The bare minimum configuration you need to do is setting `OPENAI_API_BASE` and `OPENAI_API_KEY` in `.env`.
 
-Test the aigent with with the `rake say` task.
+Test the aigent with the `say` command.
 
 ```bash
-rake say["How many fibers are intertwined in a shredded wheat biscuit?"]
+bin/aigent say "How many fibers are intertwined in a shredded wheat biscuit?"
 ```
 
-See the aigent's README (scaffold/README.md in this codebase) for more information.
+See the aigent's README for more information (`README.md` in your aigent directory or `scaffold/enlist/README.md` in this codebase).

data/lib/aigency/aigent/current_time.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Aigency
+  class Aigent
+    class CurrentTime < Aigency::Tool
+      description 'Get the current time'
+
+      parameters do
+        any_of :format, description: "Date/time format" do
+          string enum: %w[iso8601 unix]
+          'iso8601'
+        end
+      end
+
+      def execute(format: 'iso8601')
+        aigent.log.puts "[Aigent::CurrentTime] #{format}"
+        now = DateTime.now
+        case format
+        when 'iso8601'
+          { success: true, current_time: now.iso8601 }
+        when 'unix'
+          { success: true, current_time: now.to_time.to_i }
+        else
+          { success: false, error: "Invalid format: #{format}" }
+        end
+      rescue StandardError => e
+        { success: false, error: "[#{e.class}] #{e.message}"}
+      end
+    end
+  end
+end

data/lib/aigency/aigent/shell.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Aigency
+  class Aigent
+    # Commands that can be executed in aigent directories.
+    #
+    class Shell < Thor
+      include Delegator
+
+      desc "say PROMPT", "Send a prompt to the aigent"
+      def say(prompt)
+        aigent.stream prompt
+      end
+
+      desc "load FILE", "Load a prompt from a file"
+      def load(file)
+        aigent.load filename
+      end
+
+      desc "setup", "Initialize aigent plugins"
+      def setup
+        aigent.setup
+      end
+
+      desc "tools", "Get a list of available tools"
+      def tools
+        puts aigent.tools.map(&:to_s).sort
+      end
+
+      desc "status", "Get the aigent's current status"
+      def status
+        puts "Name: #{aigent.config('aigent')['name']}"
+        puts "Busy: #{aigent.busy?}"
+        if aigent.busy?
+          puts "Process: #{File.read(aigent.data('lock'))}"
+        end
+      end
+
+      desc "instructions", "List base instructions"
+      long_desc <<~DESC
+        Show all instructions that will be given to the aigent before the user
+        prompt. They typically include the IDENTITY.md file and any prompts injected
+        by installed plugins.
+      DESC
+      def instructions
+        puts aigent.instructions
+      end
+
+      desc "stream", "Tail the currently active chat stream"
+      option :follow, type: :boolean, aliases: :f, desc: "Follow the stream (tail -f)"
+      option :lines, type: :numeric, aliases: :n, desc: "Number of lines (tail -n)", default: 10
+      long_desc <<~DESC
+        This is useful for monitoring non-interactive chat streams, e.g., chat sessions
+        that were started by cron jobs or rake tasks. It runs `tail` on the current chat
+        file in the aigent's data/chats folder.
+      DESC
+      def stream
+        if aigent.busy?
+          file = Dir.glob(aigent.data('chats', '*.txt')).max { |file| File.mtime(file).to_i }
+          cmd = ['tail', file, '-n', options[:lines].to_s]
+          cmd.push '-f' if options[:follow]
+          puts "(#{file})"
+          exec *cmd
+        else
+          puts "No active chat stream."
+        end
+      end
+
+      desc "kill", "Kill a blocking process"
+      long_desc <<~DESC
+        Kill the process that owns an exclusive lock on the aigent's data/lock file.
+      DESC
+      def kill
+        if aigent.busy?
+          pid = File.read(aigent.data('lock')).to_i
+          puts "Killing process #{pid}"
+          Process.kill 'TERM', pid
+        else
+          puts "No blocking process exists."
+        end
+      end
+
+      class << self
+        def mounted? = false
+
+        def start(args = ARGV, config = {})
+          return super if mounted?
+          build('.').start(args, config)
+        end
+
+        def build(directory)
+          Class.new(self) do
+            def self.mounted? = true
+            Aigent.new(directory).plugins.each do |plugin|
+              next unless plugin.shell
+              if all_commands.key?(plugin.name)
+                raise "Plugin '#{plugin.name}' cannot register CLI command '#{plugin.name}': already taken"
+              end
+              register(plugin.shell, plugin.name, "#{plugin.name} [SUBCOMMAND ...ARGS]", "#{plugin.name} plugin commands")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aigency/aigent.rb

@@ -2,16 +2,19 @@
 
 require 'fileutils'
 require 'yaml'
+require 'set'
 
 module Aigency
   class Aigent
+    require 'aigency/aigent/current_time'
+    require 'aigency/aigent/shell'
+
     # @return [IO]
     attr_reader :log
 
     def initialize(directory)
       @base_directory = File.absolute_path(directory)
       @log = $stdout
-      load_requires
     end
 
     # @return [String]
@@ -38,30 +41,49 @@ module Aigency
     # Initialize a RubyLLM::Chat.
     #
     # @param extra [Array<String>] Additional instructions
-    # @param tools [Array<Class<Tool>>] Available tools (default is all registered tools)
+    # @param except [Array<Class<Tool>>] Tools to exclude from this chat
     # @return [RubyLLM::Chat]
-    def brief(*extra, tools: Tools.registry)
-      chat = rubyllm_context.chat(provider: :openai)
-      tools.each { |klass| chat.with_tool(klass.new(self)) }
-      chat.with_instructions(build_instructions(extra), append: true)
-      chat.with_params(max_tokens: max_tokens)
+    def brief(*extra, except: [])
+      chat = rubyllm_context.chat(provider: :openai, protocol: :chat_completions)
+      (tools - except).each { |klass| chat.with_tools(klass.new(self)) }
+      chat.with_instructions(build_instructions(extra).join, append: true)
+      chat.with_provider_options(max_tokens: max_tokens)
     end
 
-    def load filename, *extra, tools: Tools.registry, out: $stdout
-      stream File.read(filename), *extra, tools: tools, out: out
+    # Prompt a chat with a file.
+    #
+    # @param filename [String]
+    # @param extra [Array<String>] Additional instructions
+    # @param except [Array<Class<Tool>>] Tools to exclude from this chat
+    # @param out [IO]
+    # @return [RubyLLM::Chat]
+    def load filename, *extra, except: [], out: $stdout
+      stream File.read(filename), *extra, except: except, out: out
     end
 
-    def stream text, *extra, with: [], tools: Tools.registry, out: $stdout
+    # Prompt a chat.
+    #
+    # @param text [String]
+    # @param extra [Array<String>] Additional instructions
+    # @param except [Array<Class<Tool>>] Tools to exclude from this chat
+    # @param out [IO]
+    # @return [RubyLLM::Chat]
+    def stream text, *extra, attach: [], except: [], out: $stdout
       original_log = @log
       @log = out
-      response = brief(*extra, tools: tools).ask text, with: with do |chunk|
-        @log.print chunk.thinking&.text
-        @log.print chunk.content
-      end
+      response = brief(*extra, except: except).ask text, with: attach #do |chunk|
+        # @log.print chunk.thinking&.text
+      #end
+      @log.puts response.content
       @log.puts "Input tokens:    #{response.tokens.input}"
       @log.puts "Output tokens:   #{response.tokens.output}"
-      @log = original_log
       response
+    rescue StandardError => e
+      message = "[#{e.class}] #{e.message}\n" + e.backtrace.map { |line| "    #{line}\n" }.join
+      @log.puts message
+      File.write data('log', 'error.log'), "#{DateTime.now.iso8601} #{message}", mode: 'a'
+    ensure
+      @log = original_log
     end
 
     # @param name [String]
@@ -70,43 +92,16 @@ module Aigency
       configs[name] ||= read_config(name)
     end
 
-    # Initialize the aigent's tool configurations.
+    # Initialize the aigent's plugin configurations.
     #
-    # @param only [Array<String>] Limit the tools being configured
-    # @param overwrite [Boolean] Replace existing configs if true
-    def setup(only: [], overwrite: false)
-      only = [only].flatten.compact
-      config_count = 0
-      Tools.config_map.each do |name, text|
-        next unless only.empty? || only.include?(name)
-
-        dir = directory('config')
-        FileUtils.mkdir_p dir
-        path = File.join(dir, "#{name}.yml")
-        if overwrite || !File.file?(path)
-          doing = File.file?(path) ?  'Overwriting' : 'Writing new'
-          log.puts "#{doing} config for #{name}"
-          File.write path, text
-          config_count += 1
-        else
-          log.puts "Config for #{name} exists, skipping"
-        end
-      end
-      dir_count = 0
-      Tools.directories.each do |path|
-        absolute = directory(path)
-        next if File.directory?(absolute)
-
-        FileUtils.mkdir_p absolute
-        dir_count += 1
-      end
-      log.puts "#{config_count} config files initialized."
-      log.puts "#{dir_count} directories created."
+    # @return [void]
+    def setup
+      plugins.each { |plugin| boot plugin }
     end
 
     # Run code in an exclusive lock
     #
-    def lock(&block)
+    def block(&block)
       File.open(data('lock'), 'w') do |file|
         file.flock(File::LOCK_EX)
         file.write(Process.pid)
@@ -114,6 +109,8 @@ module Aigency
         block&.call
       end
     end
+    alias lock block
+    alias flock block
 
     # Run code if an exclusive lock is available or skip if a lock exists
     #
@@ -138,12 +135,56 @@ module Aigency
     end
     alias busy? locked?
 
+    # @return [String]
     def instructions
-      @instructions ||= build_instructions([])
+      @instructions ||= build_instructions([]).join("\n\n")
+    end
+
+    # @return [Array<Plugin>]
+    def plugins
+      config('aigent').fetch('plugins', [])
+                      .unshift('aigent')
+                      .uniq
+                      .map { |name| Plugin.registry[name] }
+    end
+
+    def tools
+      plugins.flat_map(&:tools).uniq
     end
 
     private
 
+    # @param plugin [Plugin]
+    def boot(plugin)
+      plugin.directories.each do |dir|
+        absolute = File.absolute_path(dir, directory)
+        if File.directory?(absolute)
+          log.puts "Directory #{dir} exists, skipping"
+        else
+          log.puts "Creating #{dir}"
+          FileUtils.mkdir_p absolute
+        end
+      end
+      unless plugin.config.empty?
+        config_file = File.absolute_path(File.join('config', "#{plugin.name}.yml"), directory)
+        if File.exist?(config_file)
+          log.puts "File config/#{plugin.name}.yml exists, skipping"
+        else
+          log.puts "Creating config/#{plugin.name}.yml"
+          File.write config_file, plugin.config
+        end
+      end
+      plugin.files.each do |file, content|
+        absolute = File.absolute_path(file, directory)
+        if File.exist?(absolute)
+          log.puts "File #{file} exists, skipping"
+        else
+          log.puts "Creating #{file}"
+          File.write absolute, content
+        end
+      end
+    end
+
     def configs
       @configs ||= {}
     end
@@ -157,7 +198,9 @@ module Aigency
       end
       full_path = File.join(directory, 'config', filename)
       if File.file?(full_path)
-        YAML.load_file(full_path)
+        content = File.read(full_path)
+                      .gsub(/\${([^}]+)}/) { ENV.fetch($1) }
+        YAML.load(content)
       else
         warn "Config name #{name} not found at #{full_path}"
         {}
@@ -176,26 +219,17 @@ module Aigency
       @base_instructions ||= identity_file? ? File.read(identity_file) : "You are a helpful AI assistant."
     end
 
+    # @return [Array<String>]
     def build_instructions(extra)
-      [base_instructions].concat tool_prompts
-                         .push "Today's date is #{DateTime.now.strftime('%B %e, %Y')}."
-                         .concat extra
-                         .join("\n\n")
+      [base_instructions].concat(tool_prompts)
+                         .concat(extra)
     end
 
     def tool_prompts
-      Tools.config_map
-           .keys
-           .map { |name| config(name)['prompt'] }
-           .compact
-    end
-
-    def load_requires
-      read_requires.each { |name| require name }
-    end
-
-    def read_requires
-      config('aigent')['require'] || []
+      # @todo Should aigents load prompts from config files that do not have
+      #   a corresponding plugin?
+      plugins.map { |plugin| config(plugin.name)['prompt'] }
+             .compact
     end
 
     def max_tokens
@@ -208,5 +242,23 @@ module Aigency
         config.openai_api_key = config('aigent')['openai_api_key']
       end
     end
+
+    Plugin.register Plugin.new(
+      'aigent',
+      tools: [CurrentTime],
+      directories: ['config', 'data/chats', 'data/log'],
+      rakefile: File.join(GEM_PATH, 'scaffold', 'aigent', 'aigent.rake'),
+      config: <<~FILE
+        name: Aigent
+        openai_api_base: ${OPENAI_API_BASE}
+        openai_api_key: ${OPENAI_API_KEY}
+        # max_tokens: 65536
+        plugins:
+          # You should only need either a workspace or a sandbox, not both. If you
+          # enable one, it's recommended that you disable the other.
+          # - sandbox
+          - workspace
+      FILE
+    )
   end
 end

data/lib/aigency/delegator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Delegator
+    module_function
+
+    def aigent
+      @aigent ||= Aigent.new(Dir.pwd)
+    end
+  end
+end

data/lib/aigency/plugin/shell.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Aigency
+  class Plugin
+    class Shell < Thor
+      include Delegator
+    end
+  end
+end

data/lib/aigency/plugin.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Aigency
+  class Plugin
+    require 'aigency/plugin/shell'
+
+    attr_reader :name, :config, :tools, :directories, :files, :rakefile, :shell
+
+    # @param name [String]
+    # @param tools [Array<Class<Tool>>]
+    # @param config [String]
+    # @param directories [Array<String>]
+    # @param files [Hash{String => String}]
+    def initialize name, tools: [], config: '', directories: [], files: {}, rakefile: nil, shell: nil
+      raise "A plugin named '#{name}' already exists" if self.class.registry.key?(name)
+      @name = name
+      @config = config
+      @tools = tools
+      @directories = directories
+      @files = files
+      @rakefile = rakefile
+      @shell = shell
+      self.class.registry[name] = self
+    end
+
+    def self.registry
+      @registry ||= {}
+    end
+
+    # @param plugin [Plugin]
+    def self.register plugin
+      registry[plugin.name] = plugin
+    end
+
+    def self.create(...)
+      register new(...)
+    end
+  end
+end

data/lib/aigency/rake.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Rake
+    def self.define(directory = '.')
+      aigent = Aigent.new(directory)
+      aigent.plugins
+            .map(&:rakefile)
+            .compact
+            .each { |rakefile| ::Rake.load_rakefile(rakefile) }
+    end
+  end
+end

data/lib/aigency/sandbox/exec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Aigency
+  module Sandbox
+    class Exec < Aigency::Tool
+      description 'Run a shell command in your sandbox'
+
+      parameters do
+        string :command, description: "The complete command to execute", required: true
+      end
+
+      def execute(command:)
+        aigent.log.puts "[Docker::Compose::Exec] #{command}"
+        output, error, result = Open3.capture3('docker', 'compose', 'exec', 'app', 'sh', '-c', command, chdir: aigent.directory)
+        { success: result.success?, stdout: output, stderr: error }
+      end
+    end
+  end
+end

data/lib/aigency/sandbox.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Sandbox
+    require 'aigency/sandbox/exec'
+
+    Plugin.register Plugin.new(
+      'sandbox',
+      tools: [Sandbox::Exec],
+      directories: ['sandbox', 'data/sandbox', 'data/sandbox_ssh'],
+      files: {
+        'sandbox/Dockerfile' => File.read(File.join(GEM_PATH, 'scaffold', 'sandbox', 'Dockerfile')),
+        'sandbox/squid.conf' => File.read(File.join(GEM_PATH, 'scaffold', 'sandbox', 'squid.conf')),
+        'docker-compose.yml' => File.read(File.join(GEM_PATH, 'scaffold', 'sandbox', 'docker-compose.yml')),
+        'data/sandbox_ssh/config' => File.read(File.join(GEM_PATH, 'scaffold', 'sandbox', 'ssh_config'))
+      },
+      config: <<~FILE
+        prompt: "The sandbox tools provide access to a Docker container."
+      FILE
+    )
+  end
+end

data/lib/aigency/shell.rb

@@ -4,12 +4,12 @@ require 'fileutils'
 require 'thor'
 
 module Aigency
+  # Top-level aigency commands for creating aigents.
+  #
   class Shell < Thor
     map %i[new] => :enlist
-    desc "enlist [DIRECTORY]", "Enable the current user as an aigent"
-    option :directory, type: :string, desc: 'Aigent directory', default: File.join(Dir.home, 'aigent')
-    def enlist
-      directory = options[:directory]
+    desc "enlist [DIRECTORY]", "Create an aigent directory"
+    def enlist directory = 'aigent'
       puts "Installing aigent at #{directory}"
       if File.exist?(directory)
         if !File.directory?(directory)
@@ -20,7 +20,7 @@ module Aigency
         end
       end
       FileUtils.mkdir(directory) unless File.directory?(directory)
-      FileUtils.copy_entry(File.join(GEM_PATH, 'scaffold'), directory)
+      FileUtils.copy_entry(File.join(GEM_PATH, 'scaffold', 'enlist'), directory)
     end
   end
 end

data/lib/aigency/tempdir/helpers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Tempdir
+    module Helpers
+      module_function
+
+      def expand_in_tempdir path
+        absolute = File.absolute_path(path, PATH)
+        raise PathError, "#{path} is not relative to tempdir" unless absolute.start_with?(PATH)
+        absolute
+      end
+    end
+  end
+end