aigency 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b9b5b24d49d87f69a17cec9420b4815db4646b37d8759951e4ced8431765800
-  data.tar.gz: 04ecc1ddb1433cfcd2c18b7c3af420df7dd52a417ef6ab90a2a3de35adb2b99b
+  metadata.gz: 8dc4124a357fd322bcbcd526f42cafc247b5f70e2a367db8bdec26dc2cd5af75
+  data.tar.gz: 8cea262865e5e6ffd4b9c1d7efc71b688814363a446684a71ae671bcbe9b316c
 SHA512:
-  metadata.gz: 6ab68e574725ebb40bad60ff6e807e480733c91f406d75c8e45b6678e16952e0cd67dde124df13ef9036ef82437bcdae97a4182169cbc615b30116f29c89667c
-  data.tar.gz: 6a4e0866fc61258b3fee11e76baeadc72ade5d5d66b87f4d8d41ad2127ac27a50a5f7ef394d0d940e03d7cc389e567f4d7e814ebb1792ef56c125904a75c4dcc
+  metadata.gz: a989b935e3554e6cbb081130910b0e81a2c0146507d81ca527024d1f356c419dc8be026d2846ee85fb8233a767a4eef0b2337d1facad1d99b840214042283972
+  data.tar.gz: c545ffd5bba322f455931ee5658cfb0c8b72d22d4da07a231214968160d17d109791ae1293ee9564532171327dec405508edb05915173e12c64744a8dbf22216

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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.
 
+## Requierments
+
+- Ruby 3.2+
+- Docker 29+
+
+(Note: Aigency is not tested on Windows. Some features are known to be Windows-incompatible.)
+
 ## Installation
 
 Install the gem from the command line:
@@ -38,7 +45,7 @@ rake setup
 
 The bare minimum configuration you need to do is setting `openai_api_base` and `openai_api_key` in `config/aigent.yml`.
 
-Test the aigent with with the `rake say` task.
+Test the aigent with the `rake say` task.
 
 ```bash
 rake say["How many fibers are intertwined in a shredded wheat biscuit?"]

data/lib/aigency/aigent.rb

@@ -2,6 +2,7 @@
 
 require 'fileutils'
 require 'yaml'
+require 'set'
 
 module Aigency
   class Aigent
@@ -38,30 +39,48 @@ 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)
+    def brief(*extra, except: [])
       chat = rubyllm_context.chat(provider: :openai)
-      tools.each { |klass| chat.with_tool(klass.new(self)) }
+      (tools - except).each { |klass| chat.with_tool(klass.new(self)) }
       chat.with_instructions(build_instructions(extra), append: true)
       chat.with_params(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|
+      response = brief(*extra, except: except).ask text, with: attach do |chunk|
         @log.print chunk.thinking&.text
         @log.print chunk.content
       end
       @log.puts "Input tokens:    #{response.tokens.input}"
       @log.puts "Output tokens:   #{response.tokens.output}"
-      @log = original_log
       response
+    rescue StandardError => e
+      @log.puts "[#{e.class}] #{e.message}"
+      @log.puts e.backtrace
+    ensure
+      @log = original_log
     end
 
     # @param name [String]
@@ -70,38 +89,11 @@ 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
@@ -142,8 +134,49 @@ module Aigency
       @instructions ||= build_instructions([])
     end
 
+    # @return [Array<Plugin>]
+    def plugins
+      config('aigent').fetch('plugins', [])
+                      .map { |name| Plugin.registry[name] }
+    end
+
+    def tools
+      plugins.flat_map(&:tools)
+    end
+
     private
 
+    # @param plugin [Plugin]
+    def boot(plugin)
+      unless plugin.config.empty?
+        config_file = File.absolute_path("#{plugin.name}.yml", directory)
+        if File.exist?(config_file)
+          log.puts "File #{plugin.name}.yml exists, skipping"
+        else
+          log.puts "Creating #{plugin.name}.yml"
+          File.write config_file, plugin.config
+        end
+      end
+      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
+      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 +190,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}"
         {}
@@ -184,10 +219,10 @@ module Aigency
     end
 
     def tool_prompts
-      Tools.config_map
-           .keys
-           .map { |name| config(name)['prompt'] }
-           .compact
+      # @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 load_requires

data/lib/aigency/plugin.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Aigency
+  class Plugin
+    attr_reader :name, :config, :tools, :directories, :files
+
+    # @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: {}
+      raise "A plugin named '#{name}' already exists" if self.class.registry.key?(name)
+      @name = name
+      @config = config
+      @tools = tools
+      @directories = directories
+      @files = files
+      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/sandbox/Dockerfile.tpl

@@ -0,0 +1,13 @@
+FROM alpine:latest
+
+RUN apk add --no-cache \
+      build-base \
+      musl-dev \
+      linux-headers \
+      git \
+      curl
+
+RUN adduser -D -h /sandbox user
+USER user
+
+CMD ["sleep", "infinity"]

data/lib/aigency/sandbox/docker-compose.yml.tpl

@@ -0,0 +1,26 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    volumes:
+      - ./data/sandbox:/sandbox
+      - ./data/sandbox_ssh:/sandbox/.ssh:ro
+    working_dir: /sandbox
+    command: ["sleep", "infinity"]
+
+  egress:
+    image: ubuntu/squid
+    networks: [sandbox, outside]
+    volumes:
+      - ./squid.conf:/etc/squid/squid.conf:ro
+
+networks:
+   sandbox:
+     internal: true
+     driver: bridge
+     driver_opts:
+       com.docker.network.bridge.gateway_mode_ipv4: isolated
+       com.docker.network.bridge.gateway_mode_ipv6: isolated
+   outside:
+     driver: bridge

data/lib/aigency/sandbox/exec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Aigency
+  module Sandbox
+    class Exec < Aigency::Tool
+      desc 'Run a shell command in your sandbox'
+
+      params 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/squid.conf.tpl

@@ -0,0 +1,23 @@
+# Allowlist-only forward proxy.
+# NOTE: this file deliberately does NOT `include /etc/squid/conf.d/*`, so the
+# rules Ubuntu ships in the image can't silently widen the allowlist.
+
+http_port 3128
+visible_hostname egress
+cache deny all                       # forward proxy only, nothing to disk
+access_log daemon:/var/log/squid/access.log
+logfile_rotate 0
+forwarded_for off                    # don't leak the container's IP downstream
+
+acl SSL_ports  port 443
+acl Safe_ports port 80 443
+acl http_targets dstdomain example.com
+
+acl SSH_ports port 22
+acl ssh_targets dstdomain example.com
+
+http_access allow CONNECT ssh_targets SSH_ports
+http_access deny !Safe_ports
+http_access deny CONNECT !SSL_ports
+http_access allow  http_targets
+http_access deny   all

data/lib/aigency/sandbox.rb

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

data/lib/aigency/shell.rb

@@ -7,9 +7,7 @@ module Aigency
   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]
+    def enlist directory = 'aigent'
       puts "Installing aigent at #{directory}"
       if File.exist?(directory)
         if !File.directory?(directory)
@@ -22,5 +20,14 @@ module Aigency
       FileUtils.mkdir(directory) unless File.directory?(directory)
       FileUtils.copy_entry(File.join(GEM_PATH, 'scaffold'), directory)
     end
+
+    # desc "setup PLUGIN [...PLUGIN]", "Initialize plugin files"
+    # option :all, type: :boolean, alias: :a, description: "Set up all plugins", default: false
+    # option :overwrite, type: :boolean, alias: :o, description: "Overwrite existing files", default: false
+    # def setup *plugins
+    #   # @todo Assuming all for now
+    #   aigent = Aigent.new(aigent)
+    #   aigent.setup
+    # end
   end
 end

data/lib/aigency/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aigency
-  VERSION = "0.2.0"
+  VERSION = '0.3.0'
 end

data/lib/aigency/workspace/cat.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Cat < Shell
+      desc 'Run the `cat` shell command in your workspace'
+
+      def command = 'cat'
+    end
+  end
+end

data/lib/aigency/workspace/cp.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Cp < Shell
+      desc 'Run the `cp` shell command in your workspace'
+
+      def command = 'cp'
+    end
+  end
+end

data/lib/aigency/workspace/diff.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Diff < Shell
+      desc 'Run the `diff` shell command in your workspace'
+
+      def command = 'diff'
+    end
+  end
+end

data/lib/aigency/workspace/grep.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Grep < Shell
+      desc 'Run the `grep` shell command in your workspace'
+
+      def command = 'grep'
+
+      def non_path_arguments = %w[PATTERN]
+
+      def prohibited_arguments = %w[-f --file]
+    end
+  end
+end

data/lib/aigency/workspace/head.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Head < Shell
+      desc 'Run the `head` shell command in your workspace'
+
+      def command = 'head'
+    end
+  end
+end

data/lib/aigency/workspace/helpers.rb

@@ -3,21 +3,58 @@
 module Aigency
   module Workspace
     module Helpers
+      module_function
+
       # @!method aigent
       #   @abstract
       #   @return [Aigency::Aigent]
 
-      # Expand a path relative to the aigent's workspace directory.
+      # Expand a path relative to the aigent's workspace.
       #
       # @raise [PathError] if the expanded path is not inside the workspace
       # @param path [String]
       # @return [String]
-      def expand_to_workspace(path)
+      def expand_in_workspace(path)
         workspace = aigent.data('workspace')
         resolved = File.expand_path(path, workspace)
         return resolved if resolved == workspace || resolved.start_with?("#{workspace}/")
+        raise PathError, "Permission denied: `#{path}` is not relative to your workspace"
+      end
+
+      # @raise [PathError] if the expanded path is not inside the workspace
+      # @param arguments [Array<String>]
+      # @param start [Integer]
+      # @return [void]
+      def validate_path_arguments(arguments, start = 0)
+        current = 0
+        glued_shorts = arguments.select { |arg| arg =~ /^-[^\-].+/ }
+        unless glued_shorts.empty?
+          raise PathError, "Permission denied: glued short options (#{glued_shorts.inspect}) are not allowed"
+        end
+        workspace = aigent.data('workspace')
+        path_arguments(arguments).each do |arg|
+          if !arg.start_with?('-')
+            current += 1
+            next unless current > start
+          end
+          path = split_path_part(arg)
+          resolved = File.expand_path(path, workspace)
+          next if resolved == workspace || resolved.start_with?("#{workspace}/")
+          raise PathError, "Permission denied: `#{path}` is not relative to your workspace"
+        end
+      end
+
+      def path_arguments(arguments)
+        arguments.reject { |arg| arg =~ /^-[^\-]$/ || (arg.start_with?('--') && !arg.include?('=')) }
+      end
 
-        raise PathError, "Permission denied: `#{path}` is not relative to your root workspace"
+      def split_path_part argument
+        return argument unless argument.start_with?('-')
+        if argument.start_with?('--')
+          argument.split('=', 2).last
+        else
+          argument[2..]
+        end
       end
     end
   end

data/lib/aigency/workspace/ls.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Ls < Shell
+      desc 'Run the `ls` shell command in your workspace'
+
+      def command = 'ls'
+    end
+  end
+end

data/lib/aigency/workspace/mkdir.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Mkdir < Shell
+      desc 'Run the `mkdir` shell command in your workspace'
+
+      def command = 'mkdir'
+    end
+  end
+end

data/lib/aigency/workspace/mv.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Mv < Shell
+      desc 'Run the `mv` shell command in your workspace'
+
+      def command = 'mv'
+    end
+  end
+end

data/lib/aigency/workspace/rm.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Rm < Shell
+      desc 'Run the `rm` shell command in your workspace'
+
+      def command = 'rm'
+    end
+  end
+end

data/lib/aigency/workspace/shell.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Aigency
+  module Workspace
+    class Shell < Tool
+      include Helpers
+
+      # @abstract
+      # @return [String]
+      def command
+        raise 'Not implemented'
+      end
+
+      def non_path_arguments = []
+
+      def prohibited_arguments = []
+
+      def execute(directory: '.', arguments: [])
+        aigent.log.puts "[Workspace::Shell] #{command} #{arguments.inspect}"
+        if any_prohibited?(arguments)
+          return { success: false, error: "Permission denied: the following arguments to `#{command}` are prohibited: #{prohibited_arguments.inspect}" }
+        end
+        resolved = expand_in_workspace(directory)
+        if arguments != ['--help'] && arguments[0, non_path_arguments.length].any? { |arg| arg.start_with?('-') }
+          return { success: false, error: non_path_argument_error }
+        end
+        validate_path_arguments(arguments, non_path_arguments.length)
+        output, error, result = Open3.capture3(command, *arguments, chdir: resolved)
+        { success: result.success?, stdout: output, stderr: error }
+      rescue StandardError => e
+        { success: false, error: "[#{e.class}] #{e.message}" }
+      end
+
+      def self.inherited other
+        other.params do
+          string :directory, description: "The working directory relative to workspace", required: false
+          array :arguments, of: :string, description: "Command arguments", required: false
+        end
+      end
+
+      private
+
+      def non_path_argument_error
+        arg_count = if non_path_arguments.length > 1
+          "#{non_path_arguments.length} arguments"
+        else
+          'argument'
+        end
+        "Permission denied: first #{arg_count} must be [#{non_path_arguments.join(', ')}] unless the only argument is `--help`"
+      end
+
+      def any_prohibited?(arguments)
+        arguments.any? { |arg| arg.start_with?(*prohibited_arguments) }
+      end
+    end
+  end
+end

data/lib/aigency/workspace/tail.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Tail < Shell
+      desc 'Run the `tail` shell command in your workspace'
+
+      def command = 'tail'
+    end
+  end
+end

data/lib/aigency/workspace/wc.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class Wc < Shell
+      desc 'Run the `wc` shell command in your workspace'
+
+      def command = 'wc'
+
+      def prohibited_arguments = %w[--files0-from]
+    end
+  end
+end

data/lib/aigency/workspace/write.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Aigency
+  module Workspace
+    # @note Unlike most of the Workspace tools, this one does not execute a shell
+    #   command. It uses ruby's File module instead.
+    #
+    class Write < Tool
+      include Helpers
+
+      desc 'Write or append to a file in the workspace'
+
+      params do
+        string :filename, description: "The filename relative to the workspace", required: true
+        string :content, description: "The data to write to the file", required: true
+        string :append, description: "Append if true or overwrite if false", required: true
+      end
+
+      def execute(filename:, content:, append:)
+        aigent.log.puts "[Workspace::Write] #{filename}"
+        resolved = expand_in_workspace(filename)
+        write_mode = if append
+          "a"
+        else
+          "w"
+        end
+        File.write resolved, content, mode: "#{write_mode}b"
+        { success: true, filename: filename }
+      rescue StandardError => e
+        { success: false, error: "[#{e.class}] #{e.message}" }
+      end
+    end
+  end
+end

data/lib/aigency/workspace.rb

@@ -2,14 +2,28 @@
 
 module Aigency
   module Workspace
+    class PathError < ArgumentError; end
+
     require 'aigency/workspace/helpers'
-    require 'aigency/workspace/directory_deleter'
-    require 'aigency/workspace/directory_reader'
-    require 'aigency/workspace/file_reader'
-    require 'aigency/workspace/file_writer'
+    require 'aigency/workspace/shell'
+    require 'aigency/workspace/cat'
+    require 'aigency/workspace/cp'
+    require 'aigency/workspace/diff'
+    require 'aigency/workspace/grep'
+    require 'aigency/workspace/ls'
+    require 'aigency/workspace/mkdir'
+    require 'aigency/workspace/mv'
+    require 'aigency/workspace/rm'
+    require 'aigency/workspace/wc'
+    require 'aigency/workspace/write'
 
-    class PathError < RuntimeError; end
+    Plugin.register Plugin.new(
+      'workspace',
+      directories: ['data/workspace'],
+      tools: [Cat, Cp, Diff, Grep, Ls, Mkdir, Mv, Rm, Wc, Write],
+      config: <<~FILE
+        prompt: "The workspace tools provide access to a readable and writeable directory."
+      FILE
+    )
   end
-
-  Tools.mkdir_p 'data/workspace'
 end

data/lib/aigency.rb

@@ -6,12 +6,13 @@ require 'ruby_llm'
 require 'aigency/version'
 require 'aigency/usability'
 require 'aigency/tool'
-require 'aigency/tools'
 require 'aigency/aigent'
+require 'aigency/plugin'
 require 'aigency/shell'
 
 # Extensions
 require 'aigency/workspace'
+require 'aigency/sandbox'
 
 module Aigency
   GEM_PATH = File.absolute_path(File.join(__dir__, '..'))

data/scaffold/.env.example

@@ -0,0 +1,4 @@
+# Environment variables to load into aigent config files
+
+OPENAI_API_BASE=https://api.openai.com/v1
+OPENAI_API_KEY=change_me

data/scaffold/Gemfile

@@ -7,4 +7,4 @@ gem "rake", "~> 13.0"
 gem "whenever", "~> 1.1"
 
 gem "ruby_llm"
-gem "aigency", path: "../aigency"
+gem "aigency"

data/scaffold/README.md

@@ -4,27 +4,23 @@ An aigent (AI agent) is an intelligent assistant powered by language models thro
 
 ## Configuration
 
-### Install dependencies
+### 1. Install dependencies
 
 ```bash
 bundle install
 ```
 
-### Initial setup
+### 2. Configure OpenAI API Connection
+
+Copy the example env file:
 
 ```bash
-rake setup
+cp .env.example .env
 ```
 
-### 1. Configure the Aigent
-
-Configure the aigent's settings in `config/aigent.yml`.
-
-#### OpenAI-Compatible Providers
-
-If you're using a local AI server or any other provider that is compatible with OpenAI, you can set the OPENAI_API_BASE config option to point there instead (e.g., `http://localhost:8080/v1`).
+Modify the `OPENAI_API_BASE` and `OPENAI_API_KEY` as needed. If you're using a local AI server or any other provider that is compatible with OpenAI, you can set the OPENAI_API_BASE config option to point there instead (e.g., `http://localhost:8080/v1`).
 
-### 2. Define the Aigent's Personality
+### 3. Define the Aigent's Personality
 
 Edit `IDENTITY.md` to define how your aigent should behave:
 
@@ -34,6 +30,22 @@ You are a professional assistant named Alex. You respond in a friendly but conci
 
 This file sets the foundation for all the aigent's responses.
 
+### 4. Configure Plugins
+
+Aigency ships with two plugins: `workspace` and `sandbox`. The `workspace` plugin is enabled by default. It's recommended that you use one or the other, but not both.
+
+The `workspace` plugin gives your aigent a directory where it can manage its own files.
+
+The `sandbox` plugin provides a container where the aigent can not only manage files, but also run commands and scripts.
+
+The `workspace` plugin is sufficient for many aigents. Switch to `sandbox` if you need your aigent to perform complex tasks.
+
+### 5. Run setup
+
+```bash
+rake setup
+```
+
 ## Usage
 
 ### Interactive Mode
@@ -41,16 +53,12 @@ This file sets the foundation for all the aigent's responses.
 Talk to your aigent using the Rake task:
 
 ```bash
-rake say["Tell me about project progress"]
+rake say["How many fibers are intertwined in a shredded wheat biscuit?"]
 ```
 
-### The Workspace
-
-Your aigent has read/write access to everything in the `data/workspace` directory.
-
 ### Scheduling Tasks
 
-The project includes the `whenever` gem for scheduling. Example of a scheduled task:
+Aigents use the `whenever` gem for scheduling. Example of a scheduled task:
 
 ```ruby
 # config/schedule.rb
@@ -69,6 +77,10 @@ bundle exec whenever --update-crontab
 
 (Note: the `whenever` gem does not work on Windows.)
 
-## Aigent Tools
+### Using the Sandbox
+
+If you enable the `sandbox` plugin, you'll need to start the container:
 
-You can give your aigent more functionality by installing additional tools. It ships with the `Workspace` tool, which gives it full read/write access to the `data/workspace` directory.
+```bash
+docker compose up -d
+```

data/scaffold/Rakefile

@@ -23,7 +23,7 @@ task :say, [:text] do |_, args|
   aigent.stream args[:text]
 end
 
-desc "Set up aigent configurations"
+desc "Set up aigent plugins"
 task :setup do
   aigent = Aigency::Aigent.new('.')
   aigent.setup

data/scaffold/config/aigent.yml

@@ -1,6 +1,9 @@
-name: an Aigent
-openai_api_base: https://api.openai.com/v1
-openai_api_key: CHANGE_ME
+name: Aigent
+openai_api_base: ${OPENAI_API_BASE}
+openai_api_key: ${OPENAI_API_KEY}
 # max_tokens: 65536
-# require:
-#   - aigency-example
+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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aigency
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Fred Snyder
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: fileutils
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +65,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
 email:
 - fsnyder@castwide.com
 executables:
@@ -64,18 +120,32 @@ files:
 - exe/aigency
 - lib/aigency.rb
 - lib/aigency/aigent.rb
+- lib/aigency/plugin.rb
+- lib/aigency/sandbox.rb
+- lib/aigency/sandbox/Dockerfile.tpl
+- lib/aigency/sandbox/docker-compose.yml.tpl
+- lib/aigency/sandbox/exec.rb
+- lib/aigency/sandbox/squid.conf.tpl
 - lib/aigency/shell.rb
 - lib/aigency/tool.rb
-- lib/aigency/tools.rb
 - lib/aigency/usability.rb
 - lib/aigency/version.rb
 - lib/aigency/workspace.rb
-- lib/aigency/workspace/directory_deleter.rb
-- lib/aigency/workspace/directory_reader.rb
-- lib/aigency/workspace/file_deleter.rb
-- lib/aigency/workspace/file_reader.rb
-- lib/aigency/workspace/file_writer.rb
+- lib/aigency/workspace/cat.rb
+- lib/aigency/workspace/cp.rb
+- lib/aigency/workspace/diff.rb
+- lib/aigency/workspace/grep.rb
+- lib/aigency/workspace/head.rb
 - lib/aigency/workspace/helpers.rb
+- lib/aigency/workspace/ls.rb
+- lib/aigency/workspace/mkdir.rb
+- lib/aigency/workspace/mv.rb
+- lib/aigency/workspace/rm.rb
+- lib/aigency/workspace/shell.rb
+- lib/aigency/workspace/tail.rb
+- lib/aigency/workspace/wc.rb
+- lib/aigency/workspace/write.rb
+- scaffold/.env.example
 - scaffold/.gitignore
 - scaffold/Gemfile
 - scaffold/IDENTITY.md

data/lib/aigency/tools.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Aigency
-  module Tools
-    # @return [Array<Class<Tool>>]
-    def self.registry
-      @registry ||= []
-    end
-
-    # @return [Hash{String => String}]
-    def self.config_map
-      @configs ||= {}
-    end
-
-    # @return [Array<String>]
-    def self.directories
-      @directories ||= []
-    end
-
-    # Register a tool.
-    #
-    # @param klass [Class<Tool>]
-    # @return [void]
-    def self.register klass
-      registry.push klass
-    end
-
-    # Define a default configuration.
-    #
-    # @param name [String] The name of the config section
-    # @param text [String] YAML-formatted config data
-    # @return [void]
-    def self.configure name, text
-      config_map[name] = text
-    end
-
-    # Define directories to be created relative to an aigent's root.
-    #
-    def self.mkdir_p *paths
-      directories.concat paths
-    end
-  end
-
-  Tools.configure 'aigent', <<~EOF
-    name: an Aigent
-    openai_api_base: https://api.openai.com/v1
-    openai_api_key: CHANGE_ME
-    require:
-      - aigency/email
-      - aigency/wikipedia
-      - aigency/workspace
-  EOF
-
-  Tools.mkdir_p 'data/chats', 'data/log'
-end

data/lib/aigency/workspace/directory_deleter.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Aigency
-  module Workspace
-    class DirectoryDeleter < Tool
-      include Helpers
-
-      desc "Delete a directory and all of its contents from your private workspace"
-
-      def execute(directory_name:)
-        aigent.log.puts "[Workspace::DirectoryDeleter] #{directory_name}"
-
-        resolved = expand_to_workspace(directory_name)
-        FileUtils.rm_rf(resolved)
-        { dirname: directory_name, success: true }
-      rescue StandardError => e
-        { success: false, error: "[#{e.class}] #{e.message}"}
-      end
-    end
-  end
-end
-
-Aigency::Tools.register Aigency::Workspace::DirectoryDeleter

data/lib/aigency/workspace/directory_reader.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Aigency
-  module Workspace
-    class DirectoryReader < Tool
-      include Helpers
-
-      desc "Get the contents of a directory from your private workspace"
-
-      def execute(directory_name:)
-        aigent.log.puts "[Workspace::DirectoryReader] Reading #{directory_name}"
-        resolved = expand_to_workspace(directory_name)
-        if File.directory?(resolved)
-          {
-            directory: directory_name,
-            success: true,
-            entries: Dir.entries(resolved)[2..]
-          }
-        else
-          {
-            directory: directory_name,
-            success: false,
-            error: "Not a directory"
-          }
-        end
-      rescue StandardError => e
-        { success: false, error: "[#{e.class}] #{e.message}" }
-      end
-    end
-  end
-end
-
-Aigency::Tools.register Aigency::Workspace::DirectoryReader

data/lib/aigency/workspace/file_deleter.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Aigency
-  module Workspace
-    class FileDeleter < Tool
-      include Helpers
-
-      desc "Delete a file from your private workspace"
-
-      def execute(filename:)
-        aigent.log.puts "[Workspace::FileDeleter] Deleting file #{filename}"
-        resolved = expand_to_workspace(filename)
-        File.delete resolved
-        { filename: filename, success: true }
-      rescue StandardError => e
-        { success: false, error: "[#{e.class}] #{e.message}" }
-      end
-    end
-  end
-end
-
-Aigency::Tools.register Aigency::Workspace::FileDeleter

data/lib/aigency/workspace/file_reader.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Aigency
-  module Workspace
-    class FileReader < Tool
-      include Helpers
-
-      desc "Read a file from your private workspace"
-
-      def execute(filename:)
-        aigent.log.puts "[Workspace::FileReader] Reading #{filename}"
-
-        resolved = expand_to_workspace(filename)
-
-        {
-          success: true,
-          filename: filename,
-          content: File.read(resolved)
-        }
-      rescue StandardError => e
-        { success: false, error: "[#{e.class}] #{e.message}"}
-      end
-    end
-  end
-end
-
-Aigency::Tools.register Aigency::Workspace::FileReader

data/lib/aigency/workspace/file_writer.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-
-module Aigency
-  module Workspace
-    class FileWriter < Tool
-      include Helpers
-
-      desc "Write a file to your private workspace"
-
-      def execute(filename:, content:)
-        aigent.log.puts "[Workspace::FileWriter] Writing #{filename}"
-
-        resolved = expand_to_workspace(filename)
-        FileUtils.mkdir_p File.dirname(resolved)
-        File.write resolved, content
-        return { filename: filename, success: true }
-      rescue StandardError => e
-        { success: false, error: "[#{e.class}] #{e.message}" }
-      end
-    end
-  end
-end
-
-Aigency::Tools.register Aigency::Workspace::FileWriter