Module events 

Event Bus — universal message ingestion for agent sessions.

Any external system (Discord, Slack, Uptime Kuma, cron, CLI, other agents) can push events into a running session. Events are formatted as system messages with source metadata, allowing the agent to respond through the appropriate channel.

Modules

format

ingest

Inbox watcher — uses inotify (via the notify crate) to instantly react to dropped event JSON files in the inbox directory. Falls back to polling.

queue

registry

socket

types

Structs

Event

EventChannel

EventContent

EventQueue

EventSender

EventSource

SessionRegistration

Enums

Severity

Functions

find_session_registration

Resolve a query to a registration. Resolution order:

format_event_for_agent

Format an event as a system message the agent can understand. Wrapped in XML tags to prevent prompt injection — the model should treat content inside tags as DATA, not instructions. Example: <event id="abc" type="alert" severity="high" source="uptime-kuma" channel="alerts">Jellyfin is DOWN.</event>

list_active_sessions

Read all registration files, prune stale ones (dead PID), return live set.

register_session

Write {session_id}.json atomically (tmp + rename). Chmod 0600 on Unix.

registry_dir

Returns the session runtime directory, creating it mode 0700 if needed.

sanitize_session_id

Sanitize a session ID for safe use in filenames and socket paths. Rejects path separators, .., and non-printable characters. Returns the sanitized string (replaces unsafe chars with _).

socket_path_for_session

Returns the Unix domain socket path for a session. Sockets live in the registry dir — $SYNAPS_RUNTIME_DIR when set (e.g. /run/user/<uid>/synaps), otherwise $SYNAPS_BASE_DIR/run (default ~/.synaps-cli/run/) — which is user-owned and mode 0700, avoiding /tmp symlink squatting and TOCTOU races.

unregister_session

Remove the registration file. Best-effort — never panics. Also removes the socket file at socket_path if it exists.

watch_inbox