174 lines
5.8 KiB
Org Mode
174 lines
5.8 KiB
Org Mode
:PROPERTIES:
|
|
:ID: gateway-telegram-skill
|
|
:CREATED: [2026-04-11 Sat 15:50]
|
|
:END:
|
|
#+TITLE: SKILL: Telegram Gateway (Universal Literate Note)
|
|
#+STARTUP: content
|
|
#+FILETAGS: :gateway:telegram:io:autonomy:
|
|
#+DEPENDS_ON: id:credentials-vault-skill
|
|
|
|
* Overview
|
|
The *Telegram Gateway* provides bi-directional communication between the Autonomous and the OpenCortex via the Telegram Bot API. It features a non-blocking polling sensor and a high-integrity actuator for outbound messaging.
|
|
|
|
* Phase A: Demand (PRD)
|
|
:PROPERTIES:
|
|
:STATUS: SIGNED
|
|
:END:
|
|
|
|
** 1. Purpose
|
|
Enable mobile/remote access to the OpenCortex via a secure Telegram bot.
|
|
|
|
** 2. Success Criteria
|
|
- [ ] *Inbound:* Messages from authorized Telegram IDs are injected into the harness Bus.
|
|
- [ ] *Outbound:* The `:telegram` target correctly routes messages to the Bot API.
|
|
- [ ] *Persistence:* The polling offset is maintained to prevent duplicate processing.
|
|
|
|
* Phase B: Blueprint (PROTOCOL)
|
|
:PROPERTIES:
|
|
:STATUS: SIGNED
|
|
:END:
|
|
|
|
** 1. Architectural Intent
|
|
The gateway operates as an autonomous background service. It uses `dexador` for HTTP polling and `cl-json` for payload processing. Authentication is enforced via a whitelist of authorized `chat_id`s.
|
|
|
|
** 2. Semantic Interfaces
|
|
- `(:type :EVENT :meta (:source :telegram :chat-id "...") :payload (:sensor :user-input :text "..."))`
|
|
- `(:type :REQUEST :target :telegram :payload (:action :message :text "..."))`
|
|
|
|
* Phase D: Build (Implementation)
|
|
|
|
** Package Context
|
|
#+begin_src lisp
|
|
#+end_src
|
|
|
|
** State: Update Tracking
|
|
Tracks the last processed message ID to prevent duplicates.
|
|
|
|
#+begin_src lisp
|
|
(defvar *telegram-last-update-id* 0)
|
|
#+end_src
|
|
|
|
** State: Polling Thread
|
|
Reference to the background thread responsible for message reception.
|
|
|
|
#+begin_src lisp
|
|
(defvar *telegram-polling-thread* nil)
|
|
#+end_src
|
|
|
|
** State: Authorized Chats
|
|
Whitelist of chat IDs permitted to interact with the agent.
|
|
|
|
#+begin_src lisp
|
|
(defvar *telegram-authorized-chats* nil
|
|
"List of chat IDs allowed to interact with the bot. Hydrated from environment.")
|
|
#+end_src
|
|
|
|
** Token Retrieval
|
|
Fetches the Bot API token from the secure vault.
|
|
|
|
#+begin_src lisp
|
|
(defun get-telegram-token () (vault-get-secret :telegram))
|
|
#+end_src
|
|
|
|
** Actuator: sendMessage
|
|
#+begin_src lisp
|
|
(defun execute-telegram-action (action context)
|
|
"Sends a message back to 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 (get-telegram-token))
|
|
(url (format nil "https://api.telegram.org/bot~a/sendMessage" token)))
|
|
(when (and token chat-id text)
|
|
(harness-log "TELEGRAM: Sending message to ~a..." chat-id)
|
|
(handler-case
|
|
(dex:post url
|
|
:headers '(("Content-Type" . "application/json"))
|
|
:content (cl-json:encode-json-to-string
|
|
`((chat_id . ,chat-id) (text . ,text))))
|
|
(error (c) (harness-log "TELEGRAM ERROR: ~a" c))))))
|
|
#+end_src
|
|
|
|
** Sensor: getUpdates & Injection
|
|
#+begin_src lisp
|
|
(defun telegram-process-updates ()
|
|
"Polls for new messages and injects them into the harness."
|
|
(let* ((token (get-telegram-token))
|
|
(url (format nil "https://api.telegram.org/bot~a/getUpdates?offset=~a"
|
|
token (1+ *telegram-last-update-id*))))
|
|
(when token
|
|
(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 *telegram-last-update-id* update-id)
|
|
(when (and text chat-id)
|
|
(harness-log "TELEGRAM: Received message from ~a" chat-id)
|
|
(inject-stimulus
|
|
(list :type :EVENT
|
|
:meta (list :source :telegram :chat-id (format nil "~a" chat-id))
|
|
:payload (list :sensor :user-input
|
|
:text text)))))))
|
|
(error (c) (harness-log "TELEGRAM POLL ERROR: ~a" c))))))
|
|
#+end_src
|
|
|
|
** Start Polling
|
|
Initializes the Telegram background thread.
|
|
|
|
#+begin_src lisp
|
|
(defun start-telegram-gateway ()
|
|
"Initializes the Telegram background thread."
|
|
(unless (and *telegram-polling-thread* (bt:thread-alive-p *telegram-polling-thread*))
|
|
(setf *telegram-polling-thread*
|
|
(bt:make-thread
|
|
(lambda ()
|
|
(loop
|
|
(telegram-process-updates)
|
|
(sleep 3)))
|
|
:name "opencortex-telegram-gateway"))
|
|
(harness-log "TELEGRAM: Gateway polling active.")))
|
|
#+end_src
|
|
|
|
** Stop Polling
|
|
Gracefully terminates the background thread.
|
|
|
|
#+begin_src lisp
|
|
(defun stop-telegram-gateway ()
|
|
(when (and *telegram-polling-thread* (bt:thread-alive-p *telegram-polling-thread*))
|
|
(bt:destroy-thread *telegram-polling-thread*)
|
|
(setf *telegram-polling-thread* nil)))
|
|
#+end_src
|
|
|
|
** Registration: Actuator
|
|
Register the Telegram channel as a physical actuator.
|
|
|
|
#+begin_src lisp
|
|
(register-actuator :telegram #'execute-telegram-action)
|
|
#+end_src
|
|
|
|
** Registration: Skill
|
|
Define the passive skill entry for the gateway.
|
|
|
|
#+begin_src lisp
|
|
(defskill :skill-gateway-telegram
|
|
:priority 150
|
|
:trigger (lambda (ctx) (declare (ignore ctx)) nil) ;; Passive, handles its own loop
|
|
:probabilistic nil
|
|
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
|
|
#+end_src
|
|
|
|
** Initialization
|
|
Trigger the polling loop upon loading.
|
|
|
|
#+begin_src lisp
|
|
(start-telegram-gateway)
|
|
#+end_src
|