passepartout/harness/act.org

#+TITLE: Stage 3: Act (act.lisp)
#+AUTHOR: Amr
#+FILETAGS: :harness:act:
#+STARTUP: content

* Stage 3: Act (act.lisp)
** Architectural Intent: Actuation
The Act stage performs the final side-effects of the reasoning engine. It routes approved actions to their registered physical actuators (CLI, Shell, Emacs, etc.) and handles the execution of internal system tools.

** Actuator Configuration
The core harness can be configured via environment variables to operate silently or target different default outputs.

#+begin_src lisp :tangle ../library/act.lisp
(in-package :opencortex)

(defvar *default-actuator* :cli)
(defvar *silent-actuators* '(:cli :system-message :emacs))

(defun initialize-actuators ()
  "Loads actuator routing defaults from environment variables and registers core harness actuators."
  (let ((def (uiop:getenv "DEFAULT_ACTUATOR"))
        (silent (uiop:getenv "SILENT_ACTUATORS")))
    (when def
      (setf *default-actuator* (intern (string-upcase def) "KEYWORD")))
    (when silent
      (setf *silent-actuators*
            (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space) s)) "KEYWORD"))
                    (str:split "," silent)))))
  
  ;; Register core harness actuators
  (register-actuator :system #'execute-system-action)
  (register-actuator :tool #'execute-tool-action)
  (register-actuator :tui (lambda (action context)
                            (let* ((meta (getf context :meta))
                                   (stream (getf meta :reply-stream)))
                              (when (and stream (open-stream-p stream))
                                (format stream "~a" (frame-message action))
                                (finish-output stream))))))
#+end_src

** Dispatching Actions
The `dispatch-action` function is the primary router. It identifies the target actuator and executes the requested side-effects.

#+begin_src lisp :tangle ../library/act.lisp
(defun dispatch-action (action context)
  (let ((payload (proto-get action :payload)))
    (when (eq (proto-get payload :sensor) :heartbeat)
      (return-from dispatch-action nil)))
  "Routes an approved action to its registered physical actuator."
  (when (and action (listp action))
    (let* ((meta (proto-get context :meta))
           (source (proto-get meta :source))
           (raw-target (or (ignore-errors (getf action :TARGET))
                           (ignore-errors (getf action :target))
                           source
                           *default-actuator*))
           (target (intern (string-upcase (string raw-target)) :keyword))
           (actuator-fn (gethash target *actuator-registry*)))
      ;; Ensure outbound action has meta if context had it
      (when (and meta (null (getf action :meta)))
        (setf (getf action :meta) meta))
      (if actuator-fn 
          (funcall actuator-fn action context) 
          (harness-log "ACT ERROR: No actuator for ~s (from ~s)" target raw-target)))))
#+end_src

** Internal System Actions
The `:system` actuator handles internal harness commands like code evaluation and dynamic skill loading.

#+begin_src lisp :tangle ../library/act.lisp
(defun execute-system-action (action context)
  "Processes internal harness commands. (ACTUATOR)"
  (declare (ignore context))
  (let* ((payload (ignore-errors (getf action :payload))) 
         (cmd (ignore-errors (getf payload :action))))
    (case cmd
      (:eval (let ((code (getf payload :code)))
               (eval (read-from-string code))))
      (:create-skill (let* ((filename (getf payload :filename)) (content (getf payload :content))
                            (skills-dir (merge-pathnames "skills/" (asdf:system-source-directory :opencortex))) 
                            (full-path (merge-pathnames filename skills-dir)))
                       (with-open-file (out full-path :direction :output :if-exists :supersede) (write-string content out))
                       (load-skill-from-org full-path)))
      (:message (harness-log "ACT [System]: ~a" (getf payload :text)))
      (t (harness-log "ACT ERROR [System]: Unknown command ~s" cmd)))))
#+end_src

** Cognitive Tool Actuation
The `:tool` actuator handles the execution of registered cognitive tools.

#+begin_src lisp :tangle ../library/act.lisp
(defun format-tool-result (tool-name result)
  "Intelligently formats a tool result for user display."
  (if (listp result)
      (let ((status (getf result :status))
            (content (getf result :content))
            (msg (getf result :message)))
        (cond ((and (eq status :success) content) (format nil "~a" content))
              ((and (eq status :error) msg) (format nil "ERROR [~a]: ~a" tool-name msg))
              (t (format nil "TOOL [~a] RESULT: ~s" tool-name result))))
      (format nil "TOOL [~a] RESULT: ~a" tool-name result)))

(defun execute-tool-action (action context)
  "Executes a registered cognitive tool. (ACTUATOR)"
  (let* ((payload (getf action :payload))
         (tool-name (getf payload :tool))
         (tool-args (getf payload :args))
         (depth (getf context :depth 0))
         (meta (getf context :meta))
         (source (getf meta :source))
         (tool (gethash (string-downcase (string tool-name)) *cognitive-tools*)))
    (if tool
        (handler-case
            (let* ((clean-args (if (and (listp tool-args) (listp (car tool-args))) (car tool-args) tool-args))
                   (result (funcall (cognitive-tool-body tool) clean-args)))
              (let ((feedback (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
                                    :PAYLOAD (list :SENSOR :tool-output :RESULT result :TOOL tool-name))))
                ;; If we have a source, send a status message with the result, formatted for humans
                (when source
                   (dispatch-action (list :TYPE :REQUEST :TARGET source 
                                          :PAYLOAD (list :ACTION :MESSAGE :TEXT (format-tool-result tool-name result))) 
                                    context))
                feedback))
          (error (c)
            (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
                  :PAYLOAD (list :SENSOR :tool-error :tool tool-name :message (format nil "~a" c)))))
        (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
              :PAYLOAD (list :SENSOR :tool-error :message "Tool not found")))))
#+end_src

** The Act Gate
The final stage of the metabolic loop. It performs a "last-mile" safety check before dispatching the action to the registered actuator.

#+begin_src lisp :tangle ../library/act.lisp
(defun act-gate (signal)
  "Final Stage: Actuation and feedback generation."
  (let* ((approved (getf signal :approved-action))
         (type (getf signal :type))
         (meta (getf signal :meta))
         (source (getf meta :source))
         (feedback nil)
         ;; context must keep internal objects for actuators to function
         (context signal))
    
    ;; 1. Last-Mile Safety Check (The Bouncer & Deterministic Gates)
    (when approved
      (let* ((original-type (getf approved :type))
             (verified (deterministic-verify approved signal)))
        (if (and (listp verified) 
                 (member (getf verified :type) '(:LOG :EVENT :log :event))
                 (not (member original-type '(:LOG :EVENT :log :event))))
            (progn
              (harness-log "ACT BLOCKED: Action failed last-mile deterministic check.")
              (setf (getf signal :approved-action) nil)
              (setf approved nil)
              (setf feedback verified))
            (progn
              (setf (getf signal :approved-action) verified)
              (setf approved verified)))))

    ;; 2. Actuation Logic
    (case type
      (:REQUEST (dispatch-action signal context))
      (:LOG (dispatch-action signal context))
      (:EVENT 
       (if approved
           (let* ((target (getf approved :target))
                  (result (dispatch-action approved context)))
             ;; If the actuator returns a signal (like :tool-output), it becomes the feedback.
             ;; Otherwise, generate tool-output feedback for non-silent actuators.
             (cond ((and (listp result) (member (getf result :type) '(:EVENT :LOG)))
                    (setf feedback result))
                   ((and result (not (member target *silent-actuators*)))
                    (setf feedback (list :type :EVENT :depth (1+ (getf signal :depth 0)) :meta meta
                                         :payload (list :sensor :tool-output :result result :tool approved))))))
           ;; If no approved action but we have a source, this might be a raw event/log stimulus.
           (when source
             (dispatch-action signal context)))))
    
    (setf (getf signal :status) :acted)
    feedback))
#+end_src