memex/notes/org-skill-inbound-gateway.org

SKILL: Inbound Multi-Channel Gateway (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Signal-cli message reception and parsing
    • Telegram Bot API webhook normalization
    • Sender verification logic (Whitelisting)
    • Autonomous stimulus injection into the Kernel Bus
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces (Lisp Signatures)
    • `inbound-message-handler`
    • `normalize-message`
    • `authenticate-sender`
    • `inject-stimulus`
    • `channel-listener`
  • 3. Example Flow (Signal)

Overview

The Inbound Multi-Channel Gateway provides the sensory interface for external messaging. It enables the agent to "hear" the user from various platforms (Signal, Telegram, SMS) by normalizing disparate inbound payloads into standard Neurosymbolic Kernel stimuli.

Phase A: Demand (PRD)

1. Purpose

Define a secure and extensible ingress for external communication channels.

2. User Needs

• Multi-Channel Ingress: Support Signal (via signal-cli), Telegram (via Bot API), and generic Webhooks.
• Payload Normalization: Convert platform-specific JSON into standard Lisp plists.
• Security & Authentication: Verify sender identity before injecting stimuli into the kernel.
• Asynchronous Reception: Non-blocking monitoring of inbound message queues.

3. Success Criteria

TODO Signal-cli message reception and parsing

TODO Telegram Bot API webhook normalization

TODO Sender verification logic (Whitelisting)

TODO Autonomous stimulus injection into the Kernel Bus

Phase B: Blueprint (PROTOCOL)

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

The Inbound Gateway should operate as a modular, asynchronous service. Each channel (Signal, Telegram, Webhook) will have its own adapter responsible for receiving and normalizing messages. A central dispatcher will then authenticate and inject these normalized messages as stimuli into the Neurosymbolic Kernel’s message bus. Error handling and logging will be crucial for observability and maintainability.

2. Semantic Interfaces (Lisp Signatures)

`inbound-message-handler`

• Purpose: Main entry point for processing inbound messages from all channels.
• Signature: `(inbound-message-handler channel message-payload)`

• Arguments:

  • `channel` (keyword): Identifies the source channel (e.g., `:signal`, `:telegram`, `:webhook`).
  • `message-payload` (string): The raw message payload received from the channel.
• Returns: Boolean indicating successful processing (T) or failure (NIL).

`normalize-message`

• Purpose: Converts a platform-specific message payload into a standard Lisp plist.
• Signature: `(normalize-message channel message-payload)`

• Arguments:

  • `channel` (keyword): The source channel.
  • `message-payload` (string): The raw message payload.
• Returns: A Lisp plist representing the normalized message. Example: `(:sender "+15551234567" :text "Hello, world!" :timestamp 1678886400)`.

`authenticate-sender`

• Purpose: Verifies the identity of the message sender based on the channel.
• Signature: `(authenticate-sender channel sender-id)`

• Arguments:

  • `channel` (keyword): The source channel.
  • `sender-id` (string): The sender's unique identifier (e.g., phone number for Signal, username for Telegram).
• Returns: Boolean indicating successful authentication (T) or failure (NIL). Consider using ACLs (Access Control Lists).

`inject-stimulus`

• Purpose: Injects a normalized message into the Neurosymbolic Kernel's message bus as a stimulus.
• Signature: `(inject-stimulus stimulus-plist)`

• Arguments:

  • `stimulus-plist` (plist): The normalized message plist.
• Returns: A unique identifier for the injected stimulus.

`channel-listener`

• Purpose: Asynchronously listens for inbound messages on a specific channel.
• Signature: `(channel-listener channel-config)`

• Arguments:

  • `channel-config` (plist): Configuration parameters specific to the channel (e.g., API key, webhook URL).
• Returns: (Non-blocking) N/A. The listener will spawn threads to handle incoming messages.

3. Example Flow (Signal)

1. `channel-listener` (for `:signal`) receives a new message via `signal-cli`.
2. The raw message is passed to `inbound-message-handler` with `channel` = `:signal`.
3. `inbound-message-handler` calls `normalize-message` to convert the Signal payload to a standard plist.
4. `inbound-message-handler` calls `authenticate-sender` to verify the sender's identity.
5. If authentication succeeds, `inbound-message-handler` calls `inject-stimulus` to inject the message into the Kernel.
6. Error handling and logging are performed at each step.