4.6 KiB
SKILL: Shell Actuator Agent (System Interface)
Overview
The Shell Actuator Agent provides the Neurosymbolic Kernel with a bridge to the host operating system. It enables the agent to execute shell commands, such as Git operations, file searches, and system diagnostics, while maintaining a strict security posture through hardcoded whitelisting.
The Interface Mandate
- Secure Actuation: Only commands explicitly listed in the security whitelist are permitted.
- Diagnostic Feedback: Capture STDOUT, STDERR, and exit codes for every command and inject them back into the cognitive loop as new stimuli.
- Loop Closure: The actuator must trigger a neural analysis of the command's output, allowing the agent to "see" the results of its actions.
- Resilience: Handle illegal command attempts by injecting a structured error response instead of allowing the execution.
Symbolic Implementation (The Logic)
The implementation focuses on the secure execution of system calls and the resulting feedback loop.
Architectural Intent: Security Whitelisting & Execution
This section defines the boundary of the agent's system powers. It strictly verifies the executable of every requested command against a whitelist before using the system's `run-program` utility. It ensures that diagnostics are always captured and returned to the core event bus.
;; 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)Architectural Intent: Feedback Perception
This trigger ensures that the skill is re-engaged the moment a shell command completes, closing the loop between action and perception.
(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))))Architectural Intent: Neuro-Cognitive Result Analysis
When a command completes, the neural layer is tasked with analyzing the diagnostics. It interprets the STDOUT and STDERR to determine if the goal was achieved, providing the user with a human-readable summary.
(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)))Registration
(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