3.9 KiB
SKILL: Org-Native Delivery Agent (External Actuator)
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
- Asynchronous Dispatch: Messages are enqueued as Org-mode headlines, ensuring delivery persistence even if external services are offline.
- Multi-Channel Support: The actuator must handle routing to different channels (Signal, Discord, Telegram) based on the action's metadata.
- 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.
(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)))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.
(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))))))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.
;; 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))orer)
#+end_src