elelem-tools 0.1.1 → 0.3.0

data/lib/elelem/tools/permissions.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Tools
+    class Permissions
+      LOAD_PATHS = [
+        File.expand_path("permissions.json", __dir__),
+        "~/.agents/permissions.json",
+        ".agents/permissions.json"
+      ].freeze
+
+      # Enter, y or yes. Anything else refuses: no, a typo, or end of input (Ctrl+D, nil).
+      YES = ["", "y", "yes"].freeze
+
+      def initialize(rules: default_rules)
+        @rules = rules
+      end
+
+      def check(tool_name, args, input:)
+        policy = @rules[tool_name.to_sym] || :ask
+        raise "Permission denied: #{tool_name}" if policy == :deny
+        return nested(tool_name, args, input, policy) if Tools.nested?
+
+        # Remember whether a person just saw and approved this call. Only then
+        # may the command it builds skip its own prompt.
+        Tools.approved = false
+        return true if policy == :allow
+
+        prompt(tool_name, args, input).tap { Tools.approved = input.interactive? }
+      end
+
+      private
+
+      def nested(tool_name, args, input, policy)
+        policy == :allow || Tools.approved? || prompt(tool_name, args, input)
+      end
+
+      def load_config(path)
+        return {} unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        return {} unless data.is_a?(Hash)
+
+        data.transform_keys(&:to_sym).transform_values { |v| v.to_s.to_sym }
+      rescue JSON::ParserError
+        {}
+      end
+
+      def prompt(tool_name, args, input)
+        return true unless input.interactive?
+
+        answer = input.ask("  Allow #{tool_name}#{subject(tool_name, args)}? [Y/n] > ")
+        raise "User denied permission: #{tool_name}" unless YES.include?(answer&.strip&.downcase)
+
+        true
+      end
+
+      # The whole command, never cut, so nothing hidden gets approved.
+      def subject(tool_name, args)
+        return "" if args.nil? || args.empty?
+
+        command = args["command"] if tool_name.to_s == "execute"
+        text = command ? command.to_s : JSON.generate(args)
+        # Control and format characters (\r, ESC, bidi overrides) could redraw the prompt.
+        " `#{text.match?(/[\p{Cc}\p{Cf}]/) ? text.dump : text}`"
+      end
+
+      def default_rules
+        LOAD_PATHS.reduce({}) do |rules, path|
+          rules.merge(load_config(File.expand_path(path)))
+        end
+      end
+    end
+  end
+end

data/lib/elelem/tools/shell.rb

@@ -1,23 +1,25 @@
 # frozen_string_literal: true
 
-Elelem::Plugins.register(:shell) do |agent|
-  strip_ansi = ->(text) do
-    text
-      .gsub(/^Script started.*?\n/, "")
-      .gsub(/\nScript done.*$/, "")
-      .gsub(/\e\].*?(?:\a|\e\\)/, "")
-      .gsub(/\e\[[0-9;?]*[A-Za-z]/, "")
-      .gsub(/\e[PX^_].*?\e\\/, "")
-      .gsub(/\e./, "")
-      .gsub(/[\b]/, "")
-      .gsub(/\r/, "")
-  end
+Elelem.configure do |config|
+  config.setup(:shell) do |agent|
+    strip_ansi = lambda do |text|
+      text
+        .gsub(/^Script started.*?\n/, "")
+        .gsub(/\nScript done.*$/, "")
+        .gsub(/\e\].*?(?:\a|\e\\)/, "")
+        .gsub(/\e\[[0-9;?]*[A-Za-z]/, "")
+        .gsub(/\e[PX^_].*?\e\\/, "")
+        .gsub(/\e./, "")
+        .gsub(/[\b]/, "")
+        .gsub("\r", "")
+    end
 
-  agent.commands.register("shell", description: "Start interactive shell") do
-    transcript = Tempfile.create do |file|
-      system("script", "-q", file.path, chdir: Dir.pwd)
-      strip_ansi.call(File.read(file.path))
+    agent.commands.register("shell", description: "Start interactive shell") do
+      transcript = Tempfile.create do |file|
+        system("script", "-q", file.path, chdir: Dir.pwd)
+        strip_ansi.call(File.read(file.path))
+      end
+      agent.conversation.add(role: "user", content: transcript) unless transcript.strip.empty?
     end
-    agent.conversation.add(role: "user", content: transcript) unless transcript.strip.empty?
   end
 end

data/lib/elelem/tools/task.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
-Elelem::Plugins.register(:task) do |agent|
-  agent.toolbox.add("task",
-    description: "Delegate subtask to focused agent (complex searches, multi-file analysis)",
-    params: { prompt: { type: "string" } },
-    required: ["prompt"]
-  ) do |args|
-    sub = agent.fork(system_prompt: "Research agent. Search, analyze, report. Be concise.")
-    sub.turn(args["prompt"])
-    { result: sub.conversation.last[:content] }
+Elelem.configure do |config|
+  config.setup(:task) do |agent|
+    agent.toolbox.add("task",
+                      description: "Delegate subtask to focused agent (complex searches, multi-file analysis)",
+                      params: { prompt: { type: "string" } },
+                      required: ["prompt"]) do |args|
+      sub = Elelem::Tools.fork(agent, template: "Research agent. Search, analyze, report. Be concise.")
+      sub.turn(args["prompt"])
+      { result: sub.conversation.last[:content] }
+    end
   end
 end

data/lib/elelem/tools/verify.rb

@@ -1,45 +1,51 @@
 # frozen_string_literal: true
 
-Elelem::Plugins.register(:verify) do |agent|
-  class Verifiers
-    SYNTAX = {
-      ".rb" => "ruby -c %{path}",
-      ".erb" => "erb -x %{path} | ruby -c",
-      ".py" => "python -m py_compile %{path}",
-      ".go" => "go vet %{path}",
-      ".rs" => "cargo check --quiet",
-      ".ts" => "npx tsc --noEmit %{path}",
-      ".js" => "node --check %{path}",
-    }.freeze
-
-    def self.for(path)
-      return [] unless path
-
-      cmds = []
-      ext = File.extname(path)
-      cmds << (SYNTAX[ext] % { path: path }) if SYNTAX[ext]
-      cmds << test_runner
-      cmds.compact
-    end
+require "shellwords"
 
-    def self.test_runner
-      %w[bin/test script/test].find { |s| File.executable?(s) }
-    end
+class Verifiers
+  SYNTAX = {
+    ".rb" => "ruby -c %{path}",
+    ".erb" => "erb -x %{path} | ruby -c",
+    ".py" => "python -m py_compile %{path}",
+    ".go" => "go vet %{path}",
+    ".rs" => "cargo check --quiet",
+    ".ts" => "npx tsc --noEmit %{path}",
+    ".js" => "node --check %{path}"
+  }.freeze
+
+  def self.for(path)
+    return [] unless path
+
+    cmds = []
+    ext = File.extname(path)
+    cmds << format(SYNTAX[ext], path: Shellwords.escape(path)) if SYNTAX[ext]
+    cmds << test_runner
+    cmds.compact
+  end
+
+  def self.test_runner
+    %w[bin/test script/test].find { |s| File.executable?(s) }
   end
+end
+
+Elelem.configure do |config|
+  config.setup(:verify) do |agent|
+    agent.toolbox.add("verify",
+                      description: "Verify file syntax and run tests",
+                      params: { path: { type: "string" } },
+                      required: ["path"]) do |args|
+      path = args["path"]
+      Verifiers.for(path).each_with_object({ verified: [] }) do |cmd, memo|
+        agent.output.doing("execute", { "command" => cmd })
+        v = agent.toolbox.run("execute", { "command" => cmd })
+        break v.to_h.merge(path: path, command: cmd) unless v.ok?
+
+        memo[:verified] << cmd
+      end
+    end
 
-  agent.toolbox.add("verify",
-    description: "Verify file syntax and run tests",
-    params: { path: { type: "string" } },
-    required: ["path"]
-  ) do |args|
-    path = args["path"]
-    Verifiers.for(path).inject({ verified: [] }) do |memo, cmd|
-      agent.terminal.say agent.toolbox.header("execute", { "command" => cmd })
-      v = agent.toolbox.run("execute", { "command" => cmd })
-      break v.merge(path: path, command: cmd) if v[:exit_status] != 0
-
-      memo[:verified] << cmd
-      memo
+    agent.toolbox.after("write") do |_, result|
+      result[:verify] = agent.toolbox.run("verify", { "path" => result[:path] }).to_h unless result[:error]
     end
   end
 end

data/lib/elelem/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Elelem
   module Tools
-    VERSION = "0.1.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/elelem/tools.rb

@@ -2,18 +2,23 @@
 
 require "elelem"
 require "pathname"
+require "shellwords"
 require "tempfile"
 
 require_relative "tools/version"
 require_relative "tools/compact"
+require_relative "tools/confirm"
 require_relative "tools/edit"
 require_relative "tools/eval"
+require_relative "tools/exec"
+require_relative "tools/fork"
 require_relative "tools/git"
 require_relative "tools/glob"
 require_relative "tools/grep"
 require_relative "tools/init"
 require_relative "tools/interview"
 require_relative "tools/list"
+require_relative "tools/permissions"
 require_relative "tools/shell"
 require_relative "tools/task"
 require_relative "tools/verify"

data/release-please-config.json

@@ -0,0 +1,13 @@
+{
+  "bootstrap-sha": "b15526735ac2f36abe2ac102d87a484ff3d3916b",
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "elelem-tools",
+      "version-file": "lib/elelem/tools/version.rb",
+      "bump-minor-pre-major": true,
+      "include-component-in-tag": false,
+      "release-as": "0.3.0"
+    }
+  }
+}

data/spec/elelem/tools/arguments_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# A pattern or path the model chooses must never become an option that runs
+# a program or deletes files.
+RSpec.describe "tool arguments that look like options" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  before do
+    File.write("notes.txt", "hello\n")
+    File.write("x.sh", "#!/bin/sh\ntouch pwned\n")
+    File.chmod(0o755, "x.sh")
+  end
+
+  it "grep searches for a pattern like --pre=CMD instead of running CMD" do
+    run_tool("grep", { "pattern" => "--pre=./x.sh" })
+
+    expect(File).not_to exist("pwned")
+  end
+
+  it "grep finds a pattern that starts with -" do
+    File.write("flags.txt", "-v\n")
+
+    expect(run_tool("grep", { "pattern" => "-v" })[:content]).to include("flags.txt")
+  end
+
+  it "glob does not take a path like -delete as an action" do
+    run_tool("glob", { "pattern" => "zzz", "path" => "-delete" })
+
+    expect(File).to exist("notes.txt")
+  end
+
+  it "list takes a path like -R as a name" do
+    expect(run_tool("list", { "path" => "-R" })).not_to be_ok
+  end
+
+  describe "git" do
+    def executes_for(call)
+      seen = []
+      session.toolbox.before("execute") do |a|
+        seen << [a["command"], Elelem::Tools.nested?]
+        raise "stopped"
+      end
+      run_tool("git", call)
+      seen
+    end
+
+    it "asks for the exact command line of a read-only command, since config can make it run programs" do
+      expect(executes_for({ "command" => "status", "args" => ["--short"] })).to eq([["git status --short", false]])
+    end
+
+    it "asks for the exact command line of any other command" do
+      expect(executes_for({ "command" => "rebase", "args" => ["-xtouch pwned", "HEAD~1"] }))
+        .to eq([["git rebase -xtouch\\ pwned HEAD\\~1", false]])
+    end
+  end
+
+  it "git still runs ordinary commands" do
+    system("git", "init", "-q", ".")
+
+    expect(run_tool("git", { "command" => "status", "args" => ["--short"] })).to be_ok
+  end
+end

data/spec/elelem/tools/edit_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+RSpec.describe "the edit tool" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  before { File.write("a.txt", "one two two") }
+
+  it "replaces the one occurrence" do
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "one", "new" => "1" })).to be_ok
+    expect(File.read("a.txt")).to eq("1 two two")
+  end
+
+  it "fails when old is missing" do
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "three", "new" => "3" })[:error]).to eq("old not found")
+    expect(File.read("a.txt")).to eq("one two two")
+  end
+
+  it "fails when old matches more than once" do
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "two", "new" => "2" })[:error]).to match(/more than once/)
+  end
+
+  it "counts overlapping matches" do
+    File.write("a.txt", "aaa")
+
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "aa", "new" => "b" })[:error]).to match(/more than once/)
+  end
+
+  it "edits a file with bytes that are not UTF-8" do
+    File.binwrite("a.txt", "caf\xE9 one")
+    run_tool("edit", { "path" => "a.txt", "old" => "one", "new" => "1" })
+
+    expect(File.binread("a.txt")).to eq("caf\xE9 1".b)
+  end
+
+  it "takes new literally" do
+    run_tool("edit", { "path" => "a.txt", "old" => "one", "new" => "\\0 \\1" })
+
+    expect(File.read("a.txt")).to eq("\\0 \\1 two two")
+  end
+end

data/spec/elelem/tools/fallback_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+RSpec.describe "the grep and glob fallbacks" do
+  # A PATH with bash and the fallbacks, but no rg or fd.
+  around do |example|
+    original = ENV.fetch("PATH")
+    Dir.mktmpdir do |dir|
+      bin = File.join(dir, "bin")
+      Dir.mkdir(bin)
+      %w[bash grep find].each do |cmd|
+        found = ENV.fetch("PATH").split(":").map { |d| File.join(d, cmd) }.find { |f| File.executable?(f) }
+        File.symlink(found, File.join(bin, cmd))
+      end
+      File.write(File.join(dir, "notes.txt"), "needle\n")
+      ENV["PATH"] = bin
+      @bin = bin
+      Dir.chdir(dir) { example.run }
+    ensure
+      ENV["PATH"] = original
+    end
+  end
+
+  it "falls back when rg is there but cannot run" do
+    File.binwrite(File.join(@bin, "rg"), "\x7FELF\x00\x00")
+    File.chmod(0o755, File.join(@bin, "rg"))
+    result = run_tool("grep", { "pattern" => "needle" })
+
+    expect(result[:content]).to include("notes.txt")
+  end
+
+  it "does not fall back when rg runs and finds nothing" do
+    File.write(File.join(@bin, "rg"), "#!/bin/sh\nexit 1\n")
+    File.chmod(0o755, File.join(@bin, "rg"))
+    result = run_tool("grep", { "pattern" => "needle" })
+
+    expect([result[:exit_status], result[:content]]).to eq([1, "no matches"])
+    expect(result).to be_ok
+  end
+
+  it "greps with grep when rg is not installed" do
+    result = run_tool("grep", { "pattern" => "needle" })
+
+    expect(result[:exit_status]).to eq(0)
+    expect(result[:content]).to include("notes.txt")
+  end
+
+  it "globs with find when fd is not installed" do
+    result = run_tool("glob", { "pattern" => "*.txt" })
+
+    expect(result[:exit_status]).to eq(0)
+    expect(result[:content]).to include("notes.txt")
+  end
+end

data/spec/elelem/tools/git_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe "the git tool" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  it "reports a failing git command as an error" do
+    result = run_tool("git", { "command" => "log" })
+
+    expect(result).not_to be_ok
+    expect(result[:error]).to include(result[:exit_status].to_s)
+  end
+
+  it "passes a working git command through" do
+    system("git", "init", "-q", ".")
+
+    expect(run_tool("git", { "command" => "status" })).to be_ok
+  end
+
+  it "asks once, showing the command line it runs" do
+    home = Dir.home
+    ENV["HOME"] = Dir.pwd # ignore ~/.agents/permissions.json
+    system("git", "init", "-q", ".")
+    prompts = []
+    input = Class.new do
+      define_method(:interactive?) { true }
+      define_method(:ask) { |text| prompts << text and "y" }
+    end.new
+    session = Elelem::Config.build_session("demo", input: input, output: Elelem::NullOutput.new)
+
+    expect(session.toolbox.run("git", { "command" => "status" })).to be_ok
+    expect(prompts).to eq(["  Allow execute `git status`? [Y/n] > "])
+  ensure
+    ENV["HOME"] = home
+  end
+end

data/spec/elelem/tools/permissions_spec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+RSpec.describe Elelem::Tools::Permissions do
+  subject { described_class.new }
+
+  let(:input) { double(ask: nil, interactive?: false) }
+
+  describe "#check" do
+    context "with default allow policies" do
+      it "allows verify, whose commands are still checked as execute" do
+        expect(subject.check("verify", { "path" => "a.rb" }, input: input)).to be true
+      end
+
+      it "allows read without prompting" do
+        expect(subject.check("read", {}, input: input)).to be true
+        expect(input).not_to have_received(:ask)
+      end
+    end
+
+    context "with deny policy" do
+      subject { described_class.new(rules: { write: :deny }) }
+
+      it { expect { subject.check("write", {}, input: input) }.to raise_error(/Permission denied/) }
+    end
+
+    context "with ask policy on a non-interactive input" do
+      it "returns true without prompting" do
+        expect(subject.check("execute", {}, input: input)).to be true
+        expect(input).not_to have_received(:ask)
+      end
+    end
+
+    context "with ask policy on an interactive input" do
+      let(:input) { double(ask: answer, interactive?: true) }
+
+      context "when approved" do
+        let(:answer) { "y" }
+
+        it "prompts and returns true" do
+          expect(subject.check("execute", {}, input: input)).to be true
+          expect(input).to have_received(:ask)
+        end
+      end
+
+      context "when denied" do
+        let(:answer) { "n" }
+
+        it { expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/) }
+      end
+
+      context "at end of input" do
+        let(:answer) { nil }
+
+        it { expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/) }
+      end
+
+      context "when the answer is an empty line" do
+        let(:answer) { "" }
+
+        it { expect(subject.check("execute", {}, input: input)).to be true }
+      end
+
+      %w[y Y yes YES].each do |yes|
+        context "when the answer is #{yes}" do
+          let(:answer) { yes }
+
+          it { expect(subject.check("execute", {}, input: input)).to be true }
+        end
+      end
+
+      %w[no np nope x].each do |other|
+        context "when the answer is #{other}" do
+          let(:answer) { other }
+
+          it { expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/) }
+        end
+      end
+
+      context "with arguments" do
+        let(:answer) { "y" }
+
+        it "shows the whole command" do
+          subject.check("execute", { "command" => "rg -n foo ." }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow execute `rg -n foo .`? [Y/n] > ")
+        end
+
+        it "escapes newlines so no line is hidden" do
+          subject.check("execute", { "command" => "ls\nrm -rf x" }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow execute `\"ls\\nrm -rf x\"`? [Y/n] > ")
+        end
+
+        it "escapes characters that could redraw the prompt" do
+          subject.check("execute", { "command" => "rm -rf ~ \r  Allow execute `ls" }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow execute `\"rm -rf ~ \\r  Allow execute `ls\"`? [Y/n] > ")
+        end
+
+        it "shows other tools' arguments as JSON" do
+          subject.check("grep", { "pattern" => "foo" }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow grep `{\"pattern\":\"foo\"}`? [Y/n] > ")
+        end
+      end
+    end
+
+    context "inside a tool that runs its own command" do
+      let(:input) { double(interactive?: true) }
+      let(:answers) { [] }
+
+      before { allow(input).to receive(:ask) { answers.shift } }
+
+      def run_tool(permissions, name)
+        permissions.check(name, { "pattern" => "x" }, input: input)
+        Elelem::Tools.nested { permissions.check("execute", { "command" => "rg -n x ." }, input: input) }
+      end
+
+      it "does not ask again after the person approved the tool" do
+        answers.push("y")
+
+        expect(run_tool(subject, "grep")).to be true
+        expect(input).to have_received(:ask).once
+      end
+
+      it "still asks for the command when the tool was allowed without asking" do
+        answers.push("n")
+        allowed = described_class.new(rules: { git: :allow })
+
+        expect { run_tool(allowed, "git") }.to raise_error(/User denied permission: execute/)
+      end
+
+      it "still refuses a denied execute" do
+        answers.push("y")
+        denied = described_class.new(rules: { execute: :deny })
+
+        expect { run_tool(denied, "grep") }.to raise_error(/Permission denied: execute/)
+      end
+
+      it "forgets the approval at the next tool" do
+        answers.push("y", "n")
+        permissions = described_class.new(rules: { list: :allow })
+        run_tool(permissions, "grep")
+
+        expect { run_tool(permissions, "list") }.to raise_error(/User denied permission: execute/)
+      end
+    end
+
+    context "with a misspelled policy on an interactive input" do
+      subject { described_class.new(rules: { execute: :dney }) }
+
+      let(:input) { double(ask: "n", interactive?: true) }
+
+      it "asks" do
+        expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/)
+        expect(input).to have_received(:ask)
+      end
+    end
+  end
+
+  describe "loading a config" do
+    it "asks for a value that is not a string" do
+      Dir.mktmpdir do |dir|
+        path = File.join(dir, "permissions.json")
+        File.write(path, '{"execute": false}')
+        rules = subject.send(:load_config, path)
+        input = double(ask: "n", interactive?: true)
+        expect { described_class.new(rules: rules).check("execute", {}, input: input) }
+          .to raise_error(/User denied permission/)
+      end
+    end
+
+    it "ignores a file that is not an object" do
+      Dir.mktmpdir do |dir|
+        path = File.join(dir, "permissions.json")
+        File.write(path, "[]")
+        expect(subject.send(:load_config, path)).to eq({})
+      end
+    end
+  end
+end