Amr Gharbeia
cd86509e3a
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 2s
- TUI: Fix stale contract (remove handle-return/*incoming-msgs*), rewrite 10->13 tests (38 checks, 100% pass). Export missing symbols from TUI package. Fix view-chat contract arity. - Gateway messaging: Add :configured key to registry (boolean, nil default). Fix contract to match (vault-based, not env-var-based). - Async Embedding Gateway: Add *embedding-backend* var, embeddings-compute function. Modify ingest-ast to populate vectors on new objects. Add EMBEDDING_PROVIDER env var support. Add Contract + 4 tests (8 checks). - Context Manager: Add /focus, /scope, /unfocus commands to TUI on-key handler. Commands degrade gracefully when context-manager not loaded. - Export hygiene: Remove 30+ ghost exports (undefined symbols). Remove duplicate/mismatched names. Exports now match actual definitions.
308 lines
13 KiB
Org Mode
308 lines
13 KiB
Org Mode
#+TITLE: SKILL: Gateway Messaging (org-skill-gateway-messaging.org)
|
|
#+AUTHOR: Agent
|
|
#+FILETAGS: :skill:gateway:messaging:
|
|
#+PROPERTY: header-args:lisp :tangle ../lisp/gateway-messaging.lisp
|
|
|
|
* Architectural Intent
|
|
|
|
~gateway-messaging~ bridges Passepartout to external messaging platforms — Telegram, Signal, and any future service that speaks HTTP or has a CLI.
|
|
|
|
Each gateway follows the same pattern:
|
|
1. **Registration** — a poll function and a send function are registered in ~*gateway-registry*~ by name ("telegram", "signal")
|
|
2. **Linking** — the user provides a token (Telegram bot token) or account name (Signal CLI); it's stored in the vault and a polling thread starts
|
|
3. **Polling** — the background thread calls the poll function every N seconds; inbound messages are injected into the daemon as ~:EVENT~ signals via ~stimulus-inject~
|
|
4. **Sending** — when ~telegram-send~ or ~signal-send~ is invoked as an actuator (registered via ~register-actuator~), it formats the message and pushes it through the platform's API
|
|
|
|
The gateway management functions (~messaging-link~, ~messaging-unlink~, ~messaging-list~, ~messaging-list-print~) are what the CLI's =passepartout gateway= subcommand calls. The old ~gateway-manager~ skill had ~gateway-link~/~gateway-unlink~/~gateway-list~ printed with the same signatures; the rename to ~messaging-*~ aligns the public API with the skill name while keeping the internal engine functions (~gateway-start~, ~gateway-stop~) as-is since they're implementation details.
|
|
|
|
This replaces the old ~gateway-manager~ skill. The Telegram/Signal platform code is unchanged; only the management entry points and the defskill name changed.
|
|
|
|
** Contract
|
|
|
|
1. (gateway-registry-initialize): populates ~*gateway-registry*~ with
|
|
~:configured~ key per platform (boolean, set when linked).
|
|
2. (messaging-link platform &key token): stores the token in the vault
|
|
and starts the gateway's polling thread.
|
|
3. (messaging-unlink platform): removes the token and stops the thread.
|
|
4. (gateway-configured-p platform): returns T if platform is configured.
|
|
5. (gateway-start platform): starts the background poll thread for a
|
|
named gateway platform.
|
|
|
|
* Implementation
|
|
|
|
** Data
|
|
#+begin_src lisp
|
|
(in-package :passepartout)
|
|
|
|
(defvar *gateway-configs* (make-hash-table :test 'equal)
|
|
"Maps platform name to plist (:token :thread :interval :enabled)")
|
|
|
|
(defvar *gateway-registry* (make-hash-table :test 'equal)
|
|
"Maps platform name to plist (:poll-fn :send-fn :default-interval)")
|
|
#+end_src
|
|
|
|
** Telegram
|
|
#+begin_src lisp
|
|
(defun telegram-get-token ()
|
|
(vault-get-secret :telegram))
|
|
|
|
(defun telegram-poll ()
|
|
"Polls Telegram for new messages and injects them into the harness."
|
|
(let* ((token (telegram-get-token)))
|
|
(when token
|
|
(let* ((last-id (getf (gethash "telegram" *gateway-configs*) :last-update-id 0))
|
|
(url (format nil "https://api.telegram.org/bot~a/getUpdates?offset=~a"
|
|
token (1+ last-id))))
|
|
(handler-case
|
|
(let* ((response (dex:get url))
|
|
(json (cl-json:decode-json-from-string response))
|
|
(updates (cdr (assoc :result json))))
|
|
(dolist (update updates)
|
|
(let* ((update-id (cdr (assoc :update--id update)))
|
|
(message (cdr (assoc :message update)))
|
|
(chat (cdr (assoc :chat message)))
|
|
(chat-id (cdr (assoc :id chat)))
|
|
(text (cdr (assoc :text message))))
|
|
(setf (getf (gethash "telegram" *gateway-configs*) :last-update-id) update-id)
|
|
(when (and text chat-id)
|
|
(log-message "TELEGRAM: Received message from ~a" chat-id)
|
|
(unless (ignore-errors (hitl-handle-message text :telegram))
|
|
(stimulus-inject
|
|
(list :type :EVENT
|
|
:meta (list :source :telegram :chat-id (format nil "~a" chat-id))
|
|
:payload (list :sensor :user-input :text text))))))))
|
|
(error (c) (log-message "TELEGRAM POLL ERROR: ~a" c)))))))
|
|
|
|
(defun telegram-send (action context)
|
|
"Sends a message via Telegram."
|
|
(declare (ignore context))
|
|
(let* ((payload (getf action :payload))
|
|
(meta (getf action :meta))
|
|
(chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
|
|
(text (or (getf payload :text) (getf action :text)))
|
|
(token (telegram-get-token)))
|
|
(when (and token chat-id text)
|
|
(handler-case
|
|
(let ((url (format nil "https://api.telegram.org/bot~a/sendMessage" token)))
|
|
(dex:post url
|
|
:headers '(("Content-Type" . "application/json"))
|
|
:content (cl-json:encode-json-to-string
|
|
`((chat_id . ,chat-id) (text . ,text)))))
|
|
(error (c) (log-message "TELEGRAM ERROR: ~a" c))))))
|
|
#+end_src
|
|
|
|
** Signal
|
|
#+begin_src lisp
|
|
(defun signal-get-account ()
|
|
(vault-get-secret :signal))
|
|
|
|
(defun signal-poll ()
|
|
"Polls Signal for new messages and injects them into the harness."
|
|
(let ((account (signal-get-account)))
|
|
(when account
|
|
(handler-case
|
|
(let* ((output (uiop:run-program (list "signal-cli" "-u" account "receive" "--json")
|
|
:output :string :error-output :string :ignore-error-status t))
|
|
(lines (cl-ppcre:split "\\\\n" output)))
|
|
(dolist (line lines)
|
|
(when (and line (> (length line) 0))
|
|
(let* ((json (ignore-errors (cl-json:decode-json-from-string line)))
|
|
(envelope (cdr (assoc :envelope json)))
|
|
(source (cdr (assoc :source envelope)))
|
|
(data-message (cdr (assoc :data-message envelope)))
|
|
(text (cdr (assoc :message data-message))))
|
|
(when (and source text)
|
|
(log-message "SIGNAL: Received message from ~a" source)
|
|
(unless (ignore-errors (hitl-handle-message text :signal))
|
|
(stimulus-inject
|
|
(list :type :EVENT
|
|
:meta (list :source :signal :chat-id source)
|
|
:payload (list :sensor :user-input :text text)))))))))
|
|
(error (c) (log-message "SIGNAL POLL ERROR: ~a" c))))))
|
|
|
|
(defun signal-send (action context)
|
|
"Sends a message via Signal."
|
|
(declare (ignore context))
|
|
(let* ((payload (getf action :payload))
|
|
(meta (getf action :meta))
|
|
(chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
|
|
(text (or (getf payload :text) (getf action :text)))
|
|
(account (signal-get-account)))
|
|
(when (and account chat-id text)
|
|
(handler-case
|
|
(uiop:run-program (list "signal-cli" "-u" account "send" "-m" text chat-id)
|
|
:output :string :error-output :string)
|
|
(error (c) (log-message "SIGNAL ERROR: ~a" c))))))
|
|
#+end_src
|
|
|
|
** Registry initialization
|
|
#+begin_src lisp
|
|
(defun gateway-registry-initialize ()
|
|
"Registers all built-in gateway handlers."
|
|
(setf (gethash "telegram" *gateway-registry*)
|
|
(list :poll-fn #'telegram-poll
|
|
:send-fn #'telegram-send
|
|
:default-interval 3
|
|
:configured nil))
|
|
(setf (gethash "signal" *gateway-registry*)
|
|
(list :poll-fn #'signal-poll
|
|
:send-fn #'signal-send
|
|
:default-interval 5
|
|
:configured nil)))
|
|
|
|
(defun gateway-configured-p (platform)
|
|
"Returns T if a platform has a stored token."
|
|
(let ((config (gethash platform *gateway-configs*)))
|
|
(and config (getf config :token))))
|
|
|
|
(defun gateway-active-p (platform)
|
|
"Returns T if a platform's polling thread is alive."
|
|
(let ((config (gethash platform *gateway-configs*)))
|
|
(and config
|
|
(getf config :thread)
|
|
(bt:thread-alive-p (getf config :thread)))))
|
|
#+end_src
|
|
|
|
** Gateway management (link/unlink)
|
|
#+begin_src lisp
|
|
(defun messaging-link (platform token)
|
|
"Links a platform with a token and starts polling."
|
|
(let ((platform-lc (string-downcase platform)))
|
|
(unless (gethash platform-lc *gateway-registry*)
|
|
(error "Unknown platform: ~a. Available: ~{~a~^, ~}"
|
|
platform (loop for k being the hash-keys of *gateway-registry* collect k)))
|
|
(when (or (null token) (zerop (length token)))
|
|
(error "Token cannot be empty"))
|
|
(log-message "MESSAGING: Linking to ~a..." platform-lc)
|
|
(gateway-unlink platform-lc)
|
|
(let* ((registry-entry (gethash platform-lc *gateway-registry*))
|
|
(interval (or (getf registry-entry :default-interval) 5)))
|
|
(setf (gethash platform-lc *gateway-configs*)
|
|
(list :token token :interval interval :enabled t))
|
|
(vault-set-secret (intern (string-upcase platform-lc) :keyword) token)
|
|
(gateway-start platform-lc)
|
|
(log-message "MESSAGING: Successfully linked ~a" platform-lc)
|
|
(format t "Successfully linked ~a gateway. Token stored securely.~%" platform-lc)
|
|
t)))
|
|
|
|
(defun messaging-unlink (platform)
|
|
"Unlinks a platform and stops its polling thread."
|
|
(let ((platform-lc (string-downcase platform)))
|
|
(gateway-stop platform-lc)
|
|
(remhash platform-lc *gateway-configs*)
|
|
(log-message "MESSAGING: Unlinked ~a" platform-lc)
|
|
(format t "Successfully unlinked ~a gateway.~%" platform-lc)
|
|
t))
|
|
#+end_src
|
|
|
|
** Polling thread management
|
|
#+begin_src lisp
|
|
(defun gateway-start (platform)
|
|
"Starts the polling thread for a linked gateway."
|
|
(let ((platform-lc (string-downcase platform)))
|
|
(let ((config (gethash platform-lc *gateway-configs*)))
|
|
(when (and config (getf config :enabled) (not (gateway-active-p platform-lc)))
|
|
(let ((poll-fn (getf (gethash platform-lc *gateway-registry*) :poll-fn)))
|
|
(when poll-fn
|
|
(let ((interval (getf config :interval)))
|
|
(setf (getf config :thread)
|
|
(bt:make-thread
|
|
(lambda ()
|
|
(loop
|
|
(when (getf (gethash platform-lc *gateway-configs*) :enabled)
|
|
(funcall poll-fn))
|
|
(sleep interval)))
|
|
:name (format nil "passepartout-~a-gateway" platform-lc)))
|
|
(log-message "MESSAGING: Started ~a polling (interval: ~as)" platform-lc interval))))))))
|
|
|
|
(defun gateway-stop (platform)
|
|
"Stops the polling thread for a gateway."
|
|
(let ((platform-lc (string-downcase platform)))
|
|
(let ((config (gethash platform-lc *gateway-configs*)))
|
|
(when (and config (getf config :thread))
|
|
(when (bt:thread-alive-p (getf config :thread))
|
|
(log-message "MESSAGING: Stopping ~a polling thread" platform-lc)
|
|
(bt:destroy-thread (getf config :thread))))
|
|
(setf (getf config :thread) nil))))
|
|
#+end_src
|
|
|
|
** Listing
|
|
#+begin_src lisp
|
|
(defun messaging-list ()
|
|
"Returns a list of all gateways with their status."
|
|
(loop for platform being the hash-keys of *gateway-registry*
|
|
collect (let ((configured (gateway-configured-p platform))
|
|
(active (gateway-active-p platform)))
|
|
(list :platform platform
|
|
:configured configured
|
|
:active active))))
|
|
|
|
(defun messaging-list-print ()
|
|
"Prints a formatted table of gateways."
|
|
(format t "~%")
|
|
(format t " ~20@A ~12@A ~10@A~%" "PLATFORM" "CONFIGURED" "STATUS")
|
|
(dolist (gw (messaging-list))
|
|
(format t " ~20@A ~12@A ~10@A~%"
|
|
(getf gw :platform)
|
|
(if (getf gw :configured) "yes" "no")
|
|
(cond
|
|
((getf gw :active) "ACTIVE")
|
|
((getf gw :configured) "stopped")
|
|
(t "not linked"))))
|
|
(format t "~%"))
|
|
#+end_src
|
|
|
|
** Boot
|
|
#+begin_src lisp
|
|
(defun gateway-start-all ()
|
|
"Called at boot to start all configured gateways."
|
|
(dolist (config (loop for platform being the hash-keys of *gateway-configs*
|
|
collect (list platform (gethash platform *gateway-configs*))))
|
|
(destructuring-bind (platform config) config
|
|
(when (and (getf config :enabled) (not (gateway-active-p platform)))
|
|
(gateway-start platform)))))
|
|
#+end_src
|
|
|
|
** Registration and boot
|
|
#+begin_src lisp
|
|
(register-actuator :telegram #'telegram-send)
|
|
(register-actuator :signal #'signal-send)
|
|
|
|
(defskill :passepartout-gateway-messaging
|
|
:priority 150
|
|
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
|
|
|
|
(gateway-registry-initialize)
|
|
(gateway-start-all)
|
|
#+end_src
|
|
|
|
#+end_src
|
|
|
|
* Test Suite
|
|
|
|
#+begin_src lisp
|
|
(eval-when (:compile-toplevel :load-toplevel :execute)
|
|
(ql:quickload :fiveam :silent t))
|
|
|
|
(defpackage :passepartout-gateway-messaging-tests
|
|
(:use :cl :fiveam :passepartout)
|
|
(:export #:messaging-suite))
|
|
|
|
(in-package :passepartout-gateway-messaging-tests)
|
|
|
|
(def-suite messaging-suite :description "Verification of Gateway Messaging")
|
|
(in-suite messaging-suite)
|
|
|
|
(test test-gateway-registry-initialize
|
|
"Contract 1: gateway-registry-initialize populates the registry with :configured key."
|
|
(clrhash passepartout::*gateway-registry*)
|
|
(gateway-registry-initialize)
|
|
(is (not (zerop (hash-table-count passepartout::*gateway-registry*))))
|
|
(let ((entry (gethash "telegram" passepartout::*gateway-registry*)))
|
|
(is (getf entry :poll-fn))
|
|
(is (getf entry :send-fn))
|
|
(is (getf entry :default-interval))
|
|
;; :configured key exists and is boolean (nil by default until linked)
|
|
(is (eq nil (getf entry :configured)))))
|
|
#+end_src
|