kijito-tools 0.2.0

package/providers/monitor/kijito-inbox-monitor@.service.template

@@ -0,0 +1,95 @@
+# Kijito Inbox Monitor - systemd USER unit template (Linux)
+#
+# The Linux counterpart to com.kijito.inbox-monitor.plist.template (macOS launchd).
+# This is a TEMPLATE UNIT in systemd's own sense: the `@` means one unit file serves
+# any number of personas, and `%i` expands to whatever follows the `@` when you
+# enable it. You do NOT edit this file per persona.
+#
+#   install:  mkdir -p ~/.config/systemd/user
+#             cp kijito-inbox-monitor@.service.template \
+#                ~/.config/systemd/user/kijito-inbox-monitor@.service
+#             systemctl --user daemon-reload
+#   run:      systemctl --user enable --now kijito-inbox-monitor@YOURPERSONA
+#   check:    systemctl --user status kijito-inbox-monitor@YOURPERSONA
+#   logs:     journalctl --user -u kijito-inbox-monitor@YOURPERSONA -f
+#
+# BEFORE IT WILL START, create the token file for that persona (0600):
+#   install -m600 /dev/null ~/.config/kijito-inbox-monitor/token.YOURPERSONA
+#   printf '%s' "$YOUR_KIJITO_API_TOKEN" > ~/.config/kijito-inbox-monitor/token.YOURPERSONA
+# A missing token is FATAL and says so - the producer will not start half-configured.
+#
+# ⚠️ THIS CAPTURES; IT DOES NOT WAKE. The unit appends one JSON event per new message
+# to ~/.local/state/kijito-inbox-monitor/events.<persona>.ndjson. Something must still
+# turn those lines into an actual wake of your agent - see "Waking your agent" in the
+# README. A running unit and a woken agent are different claims, and only the second
+# one is the point.
+#
+# Uncomment the hardening block at the bottom only after reading it - ProtectHome
+# would deny the writes this unit needs unless ReadWritePaths names them.
+#
+# ⚠️ IF YOU RUN SEVERAL PERSONAS, each gets its own instance and its own state file.
+# Never point two instances at one --state-file: it is single-writer locked, and the
+# second one will refuse to start rather than corrupt the cursor.
+#
+# ⚠️ A USER UNIT STOPS WHEN YOUR LAST SESSION ENDS, AND Restart=always DOES NOT SAVE IT.
+# That directive restarts the SERVICE; it cannot restart the user manager that hosts it.
+# `Linger=no` is the default on every machine, so this is opt-in:
+#   loginctl enable-linger "$USER"        # check: loginctl show-user "$USER" -p Linger
+# On a desktop you may never notice. On a server, or a VM you log out of, the producer
+# just stops - and nothing reports it, because a watcher cannot report its own death.
+# This is the same class as the warning above: a running unit and a woken agent are
+# different claims, and so are an ENABLED unit and a unit that survives your logout.
+
+[Unit]
+Description=Kijito inbox monitor (persona: %i)
+Documentation=https://github.com/KijitoAI/kijito-inbox-monitor
+# Start after the network is genuinely up, not merely configured: the producer's first
+# act is an HTTPS poll, and a DNS failure at boot is an avoidable alert.
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# --token-file, never an env var or an argument: it keeps the secret out of the unit
+# file, out of `systemctl show`, and out of every process listing.
+# ⚠️ THE STATE FILE IS DELIBERATELY *NOT* IN ~/.cache, AND THIS IS NOT PEDANTRY.
+# XDG defines ~/.cache as non-essential data that anything may delete at any time,
+# and cache cleaners do. But losing the state file is NOT a cache miss: with no
+# state, the producer BASELINES to the newest visible id - so the unread backlog is
+# SKIPPED, not re-fetched. Mail that would have woken you never does. (Since v0.4.x
+# that skip is at least ANNOUNCED as a `baseline_skipped` diagnostic instead of
+# happening in silence - but announced-and-skipped is still skipped.)
+# ⇒ state lives under ~/.local/state (XDG_STATE_HOME: persists between restarts).
+ExecStart=%h/.local/bin/kijito-inbox-monitor \
+  --persona %i \
+  --token-file %h/.config/kijito-inbox-monitor/token.%i \
+  --poll-seconds 30 \
+  --wait 60 \
+  --state-file %h/.local/state/kijito-inbox-monitor/%i.state \
+  --events-file %h/.local/state/kijito-inbox-monitor/events.%i.ndjson \
+  --no-content \
+  --heartbeat 900
+
+# Create the state directory before the first start, 0700. systemd will not make it
+# for you, and a missing parent is a startup failure rather than a silent skip.
+ExecStartPre=/usr/bin/install -d -m 0700 %h/.local/state/kijito-inbox-monitor
+
+# A watcher cannot report its own death, so something else must restart it.
+Restart=always
+RestartSec=15
+
+# The producer warns when its state directory is group-writable, because the events
+# file carries message bodies and the state file carries the cursor. 0077 keeps it
+# both quiet and correct.
+UMask=0077
+
+# Optional hardening - uncomment if your distro's systemd supports these (v235+).
+# The producer needs outbound HTTPS, its own $HOME paths, and nothing else.
+# ProtectSystem=strict
+# ProtectHome=read-only
+# ReadWritePaths=%h/.local/state/kijito-inbox-monitor
+# PrivateTmp=true
+# NoNewPrivileges=true
+
+[Install]
+WantedBy=default.target