#+TITLE - Shell Actuator Skill
#+AUTHOR - org-agent
#+SKILL_NAME - skill-shell-actuator

This skill gives the agent the ability to execute shell commands, protected by a strict, hardcoded whitelist.

* Sensor & State (Actuator Registration)
When this skill loads, it registers itself to handle `:shell` actions.

#+begin_src lisp
;; A strict whitelist of permitted executables
(defparameter *allowed-commands* '("ls" "git" "rg" "grep" "date" "echo" "cat"))

(defun execute-shell-safely (action)
  "System 2 strictly verifies the command against the whitelist and captures full diagnostics."
  (let* ((cmd-string (getf (getf action :payload) :cmd))
         (executable (car (uiop:split-string cmd-string :separator '(#\Space)))))
    
    (if (member executable *allowed-commands* :test #'string=)
        (progn
          (format t "Shell Actuator - Executing '~a'~%" cmd-string)
          (multiple-value-bind (stdout stderr exit-code)
              (uiop:run-program cmd-string 
                                :output :string 
                                :error-output :string 
                                :ignore-error-status t)
            ;; Inject structured diagnostics back into the core bus
            (org-agent:inject-stimulus 
             `(:type :EVENT 
               :payload (:sensor :shell-response 
                         :cmd ,cmd-string 
                         :stdout ,(or stdout "") 
                         :stderr ,(or stderr "") 
                         :exit-code ,exit-code)))))
        (progn
          (format t "Shell Actuator - BLOCKED illegal command '~a'~%" cmd-string)
          (org-agent:inject-stimulus 
           `(:type :EVENT 
             :payload (:sensor :shell-response 
                       :cmd ,cmd-string 
                       :stdout "" 
                       :stderr "ERROR - Command not in security whitelist." 
                       :exit-code 1)))))))

;; Register the actuator
(org-agent:register-actuator :shell #'execute-shell-safely)
#+end_src

* Trigger
#+begin_src lisp
(defun trigger-skill-shell-actuator (context)
  (let ((type (getf context :type))
        (payload (getf context :payload)))
    (and (eq type :EVENT)
         (eq (getf payload :sensor) :shell-response))))
#+end_src

* Neuro Prompt
#+begin_src lisp
(defun neuro-skill-shell-actuator (context)
  (let* ((p (getf context :payload))
         (cmd (getf p :cmd))
         (stdout (getf p :stdout))
         (stderr (getf p :stderr))
         (exit-code (getf p :exit-code)))
    (format nil "
      You executed the shell command - '~a'
      EXIT CODE - ~a
      
      STDOUT:
      ---
      ~a
      ---
      
      STDERR:
      ---
      ~a
      ---
      
      Analyze the diagnostics. If there was an error, explain why and suggest a fix.
      Return a Lisp plist - (:target :emacs :action :message :text \"your summary\")
    " cmd exit-code stdout stderr)))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-shell-actuator
  :priority 80
  :trigger #'trigger-skill-shell-actuator
  :neuro #'neuro-skill-shell-actuator
  :symbolic (lambda (action context) action)) ; Pass-through, safety handled by actuator fn
#+end_src