---
Proposed: 2021-01-26
Implemented: ~2022
Standardized: 2026-03-09
Protocol: agent-protocol, simplex-messaging v2
---

> **Implementation note:** Phase 1 (agent auto-ACK, store in DB, forward to client on SUB) is implemented. The GET command was added in SMP v2 for iOS NSE message retrieval. Phases 2 and 3 (fine-grained MGET/MDEL/MACK commands and autonomous agent with background polling) were not implemented.

# SMP Agent: message management

The proposal is to change the way SMP agent manages the messages from the SMP servers.

Currently, it acts just as a proxy, when it does not receive any further messages from the server until the client ACKs them. The downside with this approach is that the agent can't work autonomously from the client, and the client always has to be active to retrieve the messages from the server. So while the agent offers a convenient, higher abstraction level when it comes to establishing connections, it does not offer any advantage over message management than using SMP server directly. There is a benefit to have an agent as a local, mailbox-like layer that downloads all messages for all connections and makes them available for further processing on the application layer.

## Phase 1. Managed agent MVP

These should be sufficient for terminal chat prototype

- Agent only maintains active subscriptions to the connections that the clients explicitly requested, only during client sessions, using `SUB` command.
- Agent would automatically send `ACK` commands to SMP servers and store them in the database.
- When the client subscribes to the connection (`SUB` - subscribe and deliver all messages received from the server) the response to `SUB` command is `OK`.
- Receiving agent should maintain its own numbering in addition to the sending agent numbering, in case the sending agent message number decreases.
- When there is an active subscription, Agent forwards messages to the connected clients in the order of their arrival, without any confirmations from the clients. It is client's responsibility to track that they didn't miss any messages and request re-delivery if needed.

## Phase 2. Subscription management and message access

- When the client subscribes to the connection (`SUB` - subscribe and deliver all missed messages) the response to `SUB` command is `NOMSG` or `MID n` where n is the ID of the last received message (1-based).
- `SUB SKIP` - subscribe but only deliver the new messages
- `SUB OFF` - turn off subscription
- Messages received by the agent during the period when there was no active client subscription are not sent to the client automatically - client has to request them one by one using `MGET n` command (it can also be used to request re-delivery of old messages or for any other direct access scenario).
- Clients can delete received messages using `MDEL n` command, where `n` is a sequential agent-assigned message ID - same that was used in `MSG` delivery.
- Clients can confirm the receipt of the messages to the sender using `MACK n` command
- Client can also request the last message ID with `MLAST` command - with the same responses.

## Phase 3. Autonomous agent

- Agent maintains active subscriptions to all connections that the clients created, whether there are active sessions with the clients or not.
- `SUB ON` command would be used to receive messages from the agent, and while it is active the agent would maintain an active TCP connection(s) with the server(s) to retrieve the messages as soon as they arrive.
- In the absence of the client connection the agent would periodically check and retrieve messages from the servers, possibly up to a quota, from all active connections. If the servers do not reply, the agent could have some retry logic with exponential back-off eventually marking connections (and/or servers) as unresponsive.

This design allows to have a single agent running in the background with multiple client applications connecting to it. It provides better message delivery guarantees, assuming transient nature of SMP server storage.