gemini/shell-tools.lisp at main · jrm-code-project/gemini · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
;;; -*- Lisp -*-

(in-package "GEMINI")

(defun shell-tools-and-handlers ()
  "Return a list of shell-related functions and their handlers."
  (macrolet ((gnutil (name description)
               `(cons
                 (function-declaration
                  :name ,name
                  :description ,(format nil "Runs the `~a` command.  ~a" name description)
                  :behavior :blocking
                  :parameters (schema
                               :type :object
                               :properties (object
                                            :arguments (schema
                                                        :type :array
                                                        :items (schema :type :string)
                                                        :description ,(format nil "The arguments to pass to the ~a command." name)))
                               :required (vector :arguments))
                  :response (schema
                             :type :string
                             :description "The standard output of the command, or an error message if the command failed."))
                 (lambda (&key arguments)
                   (uiop:run-program
                    (cons ,name (coerce arguments 'list))
                    :output :string
                    :error-output :string
                    :ignore-error-status t)))))
    (list
     (gnutil "awk" "Use this command to transform structured files.")
     (cons
      (function-declaration
       :name "bash"
       :description "**This is the `bash` shell tool.  This interface allows you to excute arbitrary
command-line programs, scripts, and system utilities directly within the underlying operating system as
non-interactive subprocesses.**

When you utilize the `bash` tool, you provide:
*   The `command` you wish to run (e.g., `ls`, `grep`, `python`, `rm`).
*   A list of `arguments` to pass to that command.

Upon execution, the system runs this command, and its complete standard output (stdout) and standard error (stderr) streams are captured and returned to you as a single string. This means you will receive all text generated by the command, whether it's a successful result or an error message.

This `bash` access empowers you to perform a wide array of system-level operations, including but not limited to:

*   **File System Management:** Create, delete, move, copy, read, and write files and directories (e.g., `mkdir`, `rm`, `mv`, `cp`, `cat`, `echo \"content\" > file.txt`).
*   **Text Processing and Data Extraction:** Search for specific patterns within file contents (`grep`), perform stream editing (`sed`), or parse structured text (`awk`).
*   **System Information Retrieval:** Query details about the system, running processes (`ps`), disk usage (`df`), or network configuration.
*   **Executing Programs and Scripts:** Run any executable program or script (e.g., Python scripts, shell scripts) that is present and accessible within the environment.
*   **Chaining Commands:** You can combine multiple shell commands using standard `bash` operators (e.g., `|` for pipes, `&&` for conditional execution) within a single `bash` tool call to achieve more complex workflows.

**Important Considerations for Usage:**

*   **Non-Interactive:** Each call to the `bash` tool executes a command as a one-off subprocess. You **cannot** maintain an ongoing, interactive shell session (e.g., you cannot launch `vim` and then type commands into it). Commands must be designed to run to completion and return their output.
*   **Error Handling:** Always be prepared to parse the output for error messages, as `stderr` is included."
       :behavior :blocking
       :parameters (schema :type :object
                           :properties (object :command
                                               (schema :type :string
                                                       :description "The `command` you wish to run (e.g., `ls`, `grep`, `python`, `rm`).")
                                               :arguments
                                               (schema :type :array
                                                       :items (schema :type :string)
                                                       :description "A list of arguments to pass to the command."))
                           :required (vector :command :arguments))
       :response (schema :type :string
                         :description "The standard output of the command, or an error message if the command failed."))
      (lambda (&key command arguments)
        (uiop:run-program
         (cons command (coerce arguments 'list))
         :output :string
         :error-output :string
         :ignore-error-status t)))
     (gnutil "curl" "Use this command to fetch http pages with complex parameters.")
     (gnutil "find" "Use this command to search the file system.")
     (gnutil "grep" "Use this command to search for files with a certain regular expression.")
     (gnutil "jq" "Use this command to parse JSON objects.")
     (gnutil "sed" "Use this command to perform stream editing on text files.")
     (gnutil "sort" "Use this command to sort lines of text."))))