Skip to main content
A presence adapter translates a platform’s messages into ngram input and routes output back. It is the connection between a surface and the Entity, not another owner of cognition or memory.

​
The platform contract

ngram/presence/platforms/base.py defines the required operations:
  • Connect and disconnect.
  • Register the incoming-message callback.
  • Send a message and tool-activity notification.
  • Set presence state.
  • Extract stable person identifiers and display names.
Optional hooks cover attachments, images, audio, tool results, spatial actions, and remote-session presentation. Implement only the features your surface actually supports and return a clear unsupported result where appropriate.

​
Input and routing

Construct an Input with the platform, channel, person ID, person name, text, and supported media or metadata. Route it through the existing Entity turn path so it shares serialization and state. Register the adapter in the runtime startup path and the Entity’s platform map. Preserve delivery metadata when a turn invokes messaging or needs to resume work on a particular surface.

​
Control paths

Keep pause, cancellation, and essential status inspection outside model inference. A control that waits for the active model to agree is not a reliable operator control. Bound activity notifications and disconnect cleanup. A stale UI observer should not block the Entity or prevent another surface from receiving output.

​
Verify the boundary

Test text delivery, person mapping, media handling, reconnects, cancellation, and a simultaneous turn from another surface. Confirm that a platform identifier is not accidentally treated as a display name or a destination on a different service. Use the existing Telegram and Discord adapters as concrete implementations. For a spatial connection, start with the Presence Protocol. Source: platforms/base.py and ngram/main.py.