FEAT: Stabilize Unified Envelope Architecture & TUI UX

- Fixed background boot crash via --non-interactive flag.
- Implemented robust protocol sanitization (stripped raw streams).
- Refined TUI formatting to display human-readable tool results.
- Fixed opencortex.sh variable shadowing and connection logic.
- Resolved :target field schema validation errors.

literate/act.org

@@ -29,7 +29,12 @@ The core harness can be configured via environment variables to operate silently
   
   ;; Register core harness actuators
   (register-actuator :system #'execute-system-action)
-  (register-actuator :tool #'execute-tool-action))
+  (register-actuator :tool #'execute-tool-action)
+  (register-actuator :tui (lambda (action context)
+                            (let ((stream (getf context :reply-stream)))
+                              (when stream
+                                (format stream "~a" (frame-message action))
+                                (finish-output stream))))))
 #+end_src
 
 ** Dispatching Actions
@@ -37,13 +42,25 @@ The `dispatch-action` function is the primary router. It identifies the target a
 
 #+begin_src lisp :tangle ../src/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* ((target (or (ignore-errors (getf action :target)) *default-actuator*)) 
+    (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 ~a" target)))))
+          (harness-log "ACT ERROR: No actuator for ~s (from ~s)" target raw-target)))))
 #+end_src
 
 ** Internal System Actions
@@ -71,24 +88,43 @@ The `:system` actuator handles internal harness commands like code evaluation an
 The `:tool` actuator handles the execution of registered cognitive tools.
 
 #+begin_src lisp :tangle ../src/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)))
-              (list :type :EVENT :depth (1+ depth) :reply-stream (getf context :reply-stream)
-                    :payload (list :sensor :tool-output :result result :tool tool-name)))
+              (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) :reply-stream (getf context :reply-stream)
-                  :payload (list :sensor :tool-error :tool tool-name :message (format nil "~a" c)))))
-        (list :type :EVENT :depth (1+ depth) :reply-stream (getf context :reply-stream)
-              :payload (list :sensor :tool-error :message "Tool not found")))))
+            (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
@@ -99,7 +135,11 @@ The final stage of the metabolic loop. It performs a "last-mile" safety check be
   "Final Stage: Actuation and feedback generation."
   (let* ((approved (getf signal :approved-action))
          (type (getf signal :type))
-         (feedback nil))
+         (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
@@ -119,23 +159,22 @@ The final stage of the metabolic loop. It performs a "last-mile" safety check be
 
     ;; 2. Actuation Logic
     (case type
-      (:REQUEST (dispatch-action signal signal))
-      (:LOG (dispatch-action signal signal))
+      (:REQUEST (dispatch-action signal context))
+      (:LOG (dispatch-action signal context))
       (:EVENT 
        (if approved
            (let* ((target (getf approved :target))
-                  (result (dispatch-action approved signal)))
+                  (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)) 
-                                         :reply-stream (getf signal :reply-stream)
+                    (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 reply-stream, this might be a raw event/log stimulus.
-           (when (getf signal :reply-stream)
-             (dispatch-action signal signal)))))
+           ;; 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))

literate/communication.org

@@ -80,3 +80,71 @@ The ~communication.lisp~ module defines the low-level transport and framing logi
                        :VERSION version 
                        :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
 #+end_src
+
+** Structural Validation (communication-validator.lisp)
+The validator ensures that incoming messages adhere to the strict property list schema of the communication protocol.
+
+#+begin_src lisp :tangle ../src/communication-validator.lisp
+(in-package :opencortex)
+
+(defun validate-communication-protocol-schema (msg)
+  "Strict structural validation for incoming communication protocol messages."
+  (unless (listp msg)
+    (error "Communication Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg)))
+  
+  (let ((type (let ((raw (proto-get msg :type))) (if (keywordp raw) (intern (string-upcase (string raw)) :keyword) raw))))
+    (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS))
+      (progn (harness-log "REJECTED MSG: ~s" msg) (error "Communication Protocol Schema Error: Invalid message type '~a'" type)))
+    
+    (case type
+      (:REQUEST 
+       (unless (proto-get msg :target)
+         (error "Communication Protocol Schema Error: REQUEST missing mandatory :target"))
+       (unless (proto-get msg :payload)
+         (error "Communication Protocol Schema Error: REQUEST missing mandatory :payload")))
+      
+      (:EVENT
+       (let ((payload (proto-get msg :payload)))
+         (unless (and payload (listp payload))
+           (error "Communication Protocol Schema Error: EVENT missing or invalid :payload"))
+         (unless (or (proto-get payload :action) (proto-get payload :sensor))
+           (error "Communication Protocol Schema Error: EVENT payload must contain :action or :sensor"))))
+      
+      (:RESPONSE
+       (unless (proto-get msg :payload)
+         (error "Communication Protocol Schema Error: RESPONSE missing mandatory :payload"))))
+    
+    t))
+
+(defskill :skill-communication-protocol-validator
+  :priority 95
+  :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
+  :probabilistic nil
+  :deterministic (lambda (action ctx)
+              (declare (ignore ctx))
+              (validate-communication-protocol-schema action)
+              action))
+#+end_src
+
+** Message Framing (communication.lisp)
+Frames a message with a hex length prefix and ensures all data is serializable.
+
+#+begin_src lisp :tangle ../src/communication.lisp
+(defun sanitize-protocol-message (msg)
+  "Recursively strips non-serializable objects from a protocol plist."
+  (if (and msg (listp msg))
+      (let ((clean nil))
+        (loop for (k v) on msg by #'cddr
+              do (unless (member k '(:reply-stream :socket :stream))
+                   (push k clean)
+                   (push (if (listp v) (sanitize-protocol-message v) v) clean)))
+        (nreverse clean))
+      msg))
+
+(defun frame-message (msg)
+  "Serializes a message plist and prefixes it with a 6-character hex length."
+  (let* ((sanitized (sanitize-protocol-message msg))
+         (payload (let ((*print-pretty* nil) (*read-eval* nil)) (format nil "~s" sanitized)))
+         (len (length payload)))
+    (format nil "~6,'0x~a" len payload)))
+#+end_src

literate/perceive.org

@@ -55,8 +55,9 @@ The initial stage of the metabolic loop. It logs the signal, performs selective
   "Initial processing: Normalizes raw stimuli and updates memory."
   (let* ((payload (getf signal :payload))
          (type (getf signal :type))
+         (meta (getf signal :meta))
          (sensor (getf payload :sensor)))
-    (harness-log "GATE [Perceive]: ~a (~a)" type (or sensor "no-sensor"))
+    (harness-log "GATE [Perceive]: ~a (~a) [Source: ~s]" type (or sensor "no-sensor") (getf meta :source))
     
     (cond ((eq type :EVENT)
            (case sensor

literate/reason.org

@@ -60,20 +60,35 @@ The Reason stage is the cognitive engine of the OpenCortex. It bridges the gap b
                            (funcall prompt-generator context)
                            (let ((p (proto-get (proto-get context :payload) :text)))
                              (if (and p (stringp p)) p "Maintain metabolic stasis."))))
-           (system-prompt (format nil "IDENTITY: ~a. MANDATE: Respond with ONE Lisp plist. ~a ~a RECENT_LOGS: ~a" 
+           (system-prompt (format nil "IDENTITY: ~a. MANDATE: Respond with ONE Lisp plist. ~a ~a RECENT_LOGS: ~a
+IMPORTANT: To reply to the user, you MUST use:
+(:TYPE :REQUEST :PAYLOAD (:ACTION :MESSAGE :TEXT \"<Response Text>\"))
+
+To call a tool, you MUST use:
+(:TYPE :REQUEST :TARGET :TOOL :ACTION :CALL :TOOL \"<name>\" :ARGS (:arg1 \"val\"))
+
+PROVIDER RULE: Always use :provider :openrouter if calling LLM tools unless specified otherwise." 
                                   assistant-name global-context tool-belt system-logs)))
       (let* ((thought (probabilistic-call raw-prompt :system-prompt system-prompt :context context))
-             (cleaned (if (stringp thought) (string-trim '(#\Space #\Newline #\Tab) thought) thought)))
+             (cleaned (if (stringp thought) (string-trim '(#\Space #\Newline #\Tab) thought) thought))
+             (meta (proto-get context :meta))
+             (source (proto-get meta :source)))
         (if (and cleaned (stringp cleaned))
             (let ((*read-eval* nil))
               (if (and (> (length cleaned) 0) (char= (char cleaned 0) #\())
                   (handler-case 
                       (let ((parsed (read-from-string cleaned)))
-                        (if (and (listp parsed) (member (proto-get parsed :TYPE) '(:CHAT :REQUEST :EVENT :STATUS :RESPONSE)))
-                            parsed
-                            (list :TYPE :CHAT :TEXT cleaned)))
-                    (error (c) (list :TYPE :CHAT :TEXT cleaned)))
-                  (list :TYPE :CHAT :TEXT cleaned)))
+                        (let ((type (proto-get parsed :TYPE))
+                              (target (or (proto-get parsed :TARGET) (proto-get parsed :target))))
+                          (cond ((member type '(:REQUEST :EVENT :STATUS :RESPONSE))
+                                 (unless (proto-get parsed :target) (setf (getf parsed :target) (or source :CLI)))
+                                 parsed)
+                                ;; Handle raw plists that look like tool calls
+                                ((or (eq target :TOOL) (eq target :tool) (getf parsed :TOOL) (getf parsed :tool))
+                                 (list :TYPE :REQUEST :TARGET :TOOL :PAYLOAD parsed))
+                                (t (list :TYPE :REQUEST :TARGET (or source :CLI) :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned))))))
+                    (error (c) (list :TYPE :REQUEST :TARGET (or source :CLI) :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned))))
+                  (list :TYPE :REQUEST :TARGET (or source :CLI) :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned))))
             thought)))))
 #+end_src
 
@@ -108,7 +123,7 @@ The Reason stage is the cognitive engine of the OpenCortex. It bridges the gap b
   (let* ((type (proto-get signal :type))
          (payload (proto-get signal :payload))
          (sensor (proto-get payload :sensor)))
-    (unless (and (eq type :EVENT) (eq sensor :chat-message))
+    (unless (and (eq type :EVENT) (member sensor '(:user-input :chat-message)))
       (return-from reason-gate signal))
     (let ((candidate (think signal)))
       (if candidate

literate/tui-client.org

@@ -47,6 +47,27 @@ The OpenCortex TUI Client is a standalone Common Lisp application built on **Cro
         (nreverse clean))
       msg))
 
+(defun format-payload (payload)
+  "Extracts human-readable text from a protocol payload, handling nested tool calls."
+  (let* ((action (getf payload :ACTION))
+         (text (getf payload :TEXT))
+         (msg (getf payload :MESSAGE))
+         (tool (getf payload :TOOL))
+         (prompt (getf payload :PROMPT))
+         (args (getf payload :ARGS))
+         (result (getf payload :RESULT)))
+    (cond (text text)
+          (msg msg)
+          ((eq action :MESSAGE) (getf payload :TEXT))
+          ((and tool prompt) (format nil "THOUGHT [~a]: ~a" tool prompt))
+          ((and tool args) 
+           (let ((inner-prompt (or (getf args :PROMPT) (getf args :TEXT))))
+             (if inner-prompt
+                 (format nil "THOUGHT [~a]: ~a" tool inner-prompt)
+                 (format nil "CALL [~a] (ARGS: ~s)" tool args))))
+          (result (format nil "RESULT: ~a" result))
+          (t (format nil "~s" payload)))))
+
 (defun listen-thread ()
   (loop while *is-running* do
     (handler-case
@@ -65,8 +86,12 @@ The OpenCortex TUI Client is a standalone Common Lisp application built on **Cro
                        (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" 
                                                    (or (getf msg :SCRIBE) (getf msg :scribe))
                                                    (or (getf msg :GARDENER) (getf msg :gardener)))))
-                      ((and (listp msg) (eq type :CHAT))
-                       (let ((text (or (getf msg :TEXT) (getf msg :text)))) (when text (enqueue-msg text))))
+                      ((and (listp msg) (member type '(:REQUEST :RESPONSE :LOG)))
+                       (let ((formatted (format-payload payload)))
+                         (when formatted (enqueue-msg formatted))))
+                      ((and (listp msg) (eq type :EVENT) (eq (getf payload :SENSOR) :TOOL-OUTPUT))
+                       (let ((formatted (format-payload payload)))
+                         (when formatted (enqueue-msg formatted))))
                       (t (harness-log "TUI: Ignored unknown type ~a" type)))))
             (when (eq raw-msg :eof) (setf *is-running* nil))
             (when (eq raw-msg :error) (setf *status-text* "Protocol Error"))))
@@ -126,7 +151,9 @@ The OpenCortex TUI Client is a standalone Common Lisp application built on **Cro
                        ;; Local Echo
                        (enqueue-msg (concatenate 'string "> " cmd))
                        ;; Send to Brain
-                       (let ((framed (opencortex:frame-message (format nil "~s" (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
+                       (let ((framed (opencortex:frame-message (list :TYPE :EVENT 
+                                                                    :META (list :SOURCE :tui :SESSION-ID "default")
+                                                                    :PAYLOAD (list :SENSOR :user-input :TEXT cmd)))))
                          (format *stream* "~a" framed)
                          (finish-output *stream*)))
                      (when (string= cmd "/exit") (setf *is-running* nil))))