memex/notes/org-skill-shell-actuator.org

SKILL: Shell Actuator Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Whitelist Enforcement
    • Diagnostic Capture
    • Result Analysis Loop
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Whitelisting & Execution
  • Feedback Perception
  • Neuro-Cognitive Analysis
• Registration

Overview

The Shell Actuator Agent provides the bridge to the host operating system. It enables secure command execution while maintaining a strict security posture through whitelisting and diagnostic feedback loops.

Phase A: Demand (PRD)

1. Purpose

Define a secure, diagnostic-rich interface for host OS interaction.

2. User Needs

• Secure Actuation: Strict whitelist of permitted commands.
• Diagnostic Feedback: Capture STDOUT, STDERR, and exit codes.
• Loop Closure: Automatic neural analysis of command results.
• Resilience: Graceful handling of blocked or failed commands.

3. Success Criteria

TODO Whitelist Enforcement

TODO Diagnostic Capture

TODO Result Analysis Loop

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

Interfaces for secure system calls. State is event-driven via the core kernel bus.

2. Semantic Interfaces

(defun execute-shell-safely (action)
  "Verifies command against whitelist and captures diagnostics.")

(defun trigger-skill-shell-actuator (context)
  "Monitors for shell-response events.")

(defun neuro-skill-shell-actuator (context)
  "Neural interpretation of command diagnostics.")

Phase D: Build (Implementation)

Whitelisting & Execution

(defparameter *allowed-commands* '("ls" "git" "rg" "grep" "date" "echo" "cat"))

(defun execute-shell-safely (action)
  (let* ((cmd-string (getf (getf action :payload) :cmd))
         (executable (car (uiop:split-string cmd-string :separator '(#\Space)))))
    (if (member executable *allowed-commands* :test #'string=)
        (multiple-value-bind (stdout stderr exit-code)
            (uiop:run-program cmd-string :output :string :error-output :string :ignore-error-status t)
          (org-agent:inject-stimulus 
           `(:type :EVENT :payload (:sensor :shell-response :cmd ,cmd-string :stdout ,(or stdout "") :stderr ,(or stderr "") :exit-code ,exit-code))))
        (org-agent:inject-stimulus 
         `(:type :EVENT :payload (:sensor :shell-response :cmd ,cmd-string :stdout "" :stderr "ERROR - Command not in security whitelist." :exit-code 1))))))

Feedback 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))))

Neuro-Cognitive Analysis

(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 "Command: ~a (Exit: ~a)~%STDOUT: ~a~%STDERR: ~a" 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))