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

DaemonPaths

Files the synaps daemon keeps under registry_dir() (0700). One daemon per profile: daemon.{sock,lock,json,pid} or daemon-<P>.{…}.

Event

EventChannel

EventContent

EventQueue

EventSender

EventSource

SessionEndpoint

Owns a bound, published generation and its captured runtime directory. A timestamp/hash collision fails binding without replacing the prior socket. Unix lock-contention leftovers are repaired on the next successful scan; Windows card cleanup under contention requires retry or own-PID reload sweep. No asynchronous task can bind after this guard is dropped.

SessionRegistration

Enums

Severity

Constants

REGISTRATION_KIND

Discriminator written into every registration so the registry can tell its own files from other *.json sharing the run dir (daemon.json, tooling drops). Files missing it (older binaries) are treated as sessions.

Functions

daemon_paths

Daemon file paths for a profile, under registry_dir().

daemon_paths_in

Same, rooted at an explicit dir (tests; --socket overrides only .sock).

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 legacy Unix socket path for a session. Active endpoint clients must read SessionRegistration::socket_path: new endpoints use bounded generation names, not this pre-publication helper. 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.

sweep_stale_registrations

Remove registrations that no running session can own and return how many were removed. Always: an owner pid that no longer exists. With own_pid (the daemon, at startup): also registrations naming that pid, which can only be leftovers. A reload re-execs the same pid without running any session’s shutdown, and the new image has not registered anything yet when it sweeps.

unregister_owned

Remove reg’s registration and socket, but only while the file on disk is still this exact registration (same owner pid, start time and socket).

unregister_session

Operator removal by ID (not owner-scoped). No runtime teardown uses this. Remove only a valid matching registration. Best-effort — never panics. Also removes the socket file at socket_path if it exists.

update_session_name

Rewrite {session_id}.json with a new name (rename / saveas). The rest of the record (socket, pid, started_at) is kept. Errors when there is no registration to update.

watch_inbox