#+TITLE: SKILL: Org-Native Delivery Agent (External Actuator)
#+ID: skill-org-delivery-agent
#+STARTUP: content

* Overview
The **Org-Native Delivery Agent** provides the primary outbound actuator for external messaging. It follows the "Inbox-as-a-Queue" pattern, appending structured headlines to a central delivery file which is then monitored by external bridges (Signal, Telegram, etc.).

* The Delivery Mandate
1. **Asynchronous Dispatch:** Messages are enqueued as Org-mode headlines, ensuring delivery persistence even if external services are offline.
2. **Multi-Channel Support:** The actuator must handle routing to different channels (Signal, Discord, Telegram) based on the action's metadata.
3. **Structured Provenance:** Every enqueued message must include a timestamp and recipient identifier.

* Symbolic Implementation (The Logic)
The implementation focuses on the file-based queueing system.

** Architectural Intent: Timestamp Normalization
Ensures that all enqueued messages are marked with a standard Org-mode timestamp for easy auditing and history tracking.

#+begin_src lisp
(defun format-universal-time-org (ut)
  "Format universal time as a standard Org-mode timestamp string."
  (multiple-value-bind (second minute hour day month year day-of-week)
      (decode-universal-time ut)
    (declare (ignore second day-of-week))
    (format nil "~4,'0d-~2,'0d-~2,'0d ~a ~2,'0d:~2,'0d" 
            year month day 
            (nth (nth-value 6 (decode-universal-time ut)) '("Mon" "Tue" "Wed" "Thu" "Fri" "Sat" "Sun"))
            hour minute)))
#+end_src

** Architectural Intent: Queue Actuation
This function physically writes the enqueued message to the `delivery.org` file. It handles environment-based routing and provides robust error logging for the kernel.

#+begin_src lisp
(defun execute-org-delivery (action)
  "Appends the message intent to the native Org-mode delivery file."
  (let* ((payload (getf action :payload))
         (text (getf payload :text))
         (channel (or (getf payload :channel) :signal))
         ;; Support Telegram and Discord identifiers if provided
         (to (or (getf payload :to) 
                 (case (or (getf payload :channel) :signal)
                   (:telegram (org-agent::get-env "TELEGRAM_CHAT_ID"))
                   (:discord (org-agent::get-env "DISCORD_WEBHOOK_URL"))
                   (t (org-agent::get-env "RECIPIENT_ID")))))
         (timestamp (format-universal-time-org (get-universal-time)))
         (system-dir (org-agent::get-env "SYSTEM_DIR" "system/"))
         (delivery-file (format nil "~a/delivery.org" system-dir)))
    
    (kernel-log "ACTUATOR [Org-Delivery] - Enqueueing ~a message for ~a..." channel to)
    
    (let ((entry (format nil "* TODO Message to ~a~%  :PROPERTIES:~%  :CHANNEL: ~a~%  :ENQUEUED_AT: [~a]~%  :STATUS: pending~%  :END:~%~%  ~a~%~%" 
                         to channel timestamp text)))
      
      (handler-case
          (with-open-file (out delivery-file 
                                :direction :output 
                                :if-exists :append 
                                :if-does-not-exist :create)
            (write-string entry out)
            (kernel-log "ACTUATOR [Org-Delivery] - Entry appended to ~a" delivery-file))
        (error (c)
          (kernel-log "ACTUATOR [Org-Delivery] ERROR - Failed to write to file - ~a" c))))))
#+end_src

* Registration
** Architectural Intent: Core Integration
Registers the `:delivery` target with the kernel's event bus, allowing any skill to request external communication through a unified interface.

#+begin_src lisp
;; Register the actuator with the core Event Bus
(org-agent:register-actuator :delivery #'execute-org-delivery)

;; Register as a skill so it appears on the dashboard
(defskill :skill-org-delivery
  :priority 100 ; Actuators are high priority
  :trigger (lambda (context) nil) ; No cognitive trigger, actuator only
  :neuro (lambda (context) nil)
  :symbolic (lambda (action context) action))
#+end_src
orer)
#+end_src