admin/Linux_post_install
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Matrix/Synapse sender + listener — second notify platform (telegram,matrix)

Browse Source 
pos communication matrix sender: send (plain/--markdown/--room), login
(password->access token via m.login.password), test. Implements the
lib/notify.sh sender contract, so NOTIFY_PLATFORM=telegram,matrix now
fans out for real; matrix.env config scope registered for pos config.

pos communication matrix listener: systemd user daemon long-polling
/sync (since token, compact m.room.message filter); reacts to own user's
messages (/ and ! both resolve), threaded m.in_reply_to replies, @quiet
marker, ai bridge with per-room session, interactive editor. Added to
INTERACTIVE_CMDS.

Docs: POS.md, howto/communication.md, HOWTO.md, usage EXAMPLES.
Verified against a mock homeserver (send shape, login, owner filter,
replies, exit codes, editor). make gen && make check green.
This commit is contained in:
Your Name
2026-08-09 20:19:07 +00:00
parent 6e437cace8
commit b74dfffd0b
9 changed files with 945 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOC/AGENT_Context_Project.md
+22 -16
View File
@@ -10,19 +10,19 @@
<!-- GEN:START docmap -->
| ## 1. Project Overview | 28–43 |
| ## 2. Directory Structure | 44–184 |
| ## 3. Installation Flow | 185–237 |
| ## 4. The `pos` CLI System | 238–302 |
| ## 5. Shared Library — `lib/common.sh` | 303–334 |
| ## 6. Docker Compose / ScaleTail | 335–377 |
| ## 7. Optional Apps (`apps/`) | 378–407 |
| ## 8. Entertainment Module | 408–421 |
| ## 9. Systemd Services | 422–434 |
| ## 10. Configuration Files | 435–461 |
| ## 11. Coding Conventions | 462–494 |
| ## 12. Development Workflow | 495–547 |
| ## 13. Key File Quick Reference | 548–599 |
| ## 14. Common Tasks for Agents | 600–625 |
| ## 2. Directory Structure | 44–186 |
| ## 3. Installation Flow | 187–239 |
| ## 4. The `pos` CLI System | 240–306 |
| ## 5. Shared Library — `lib/common.sh` | 307–338 |
| ## 6. Docker Compose / ScaleTail | 339–381 |
| ## 7. Optional Apps (`apps/`) | 382–411 |
| ## 8. Entertainment Module | 412–425 |
| ## 9. Systemd Services | 426–438 |
| ## 10. Configuration Files | 439–465 |
| ## 11. Coding Conventions | 466–498 |
| ## 12. Development Workflow | 499–551 |
| ## 13. Key File Quick Reference | 552–605 |
| ## 14. Common Tasks for Agents | 606–631 |
<!-- GEN:END docmap -->
## 1. Project Overview
@@ -59,6 +59,8 @@ Linux_post_install/
│ ├── pos # Main dispatcher — smart arg matching to pos-* scripts
<!-- GEN:START tree -->
│ ├── pos-ai-gemini # Chat with Google Gemini (ask, chat, models, sessions)
│ ├── pos-communication-matrix-listener # Matrix listener: map /command → bash, run them on room messages
│ ├── pos-communication-matrix-sender # Send messages to a Matrix room via the client-server API (send, test, login)
│ ├── pos-communication-telegram-listener # Telegram bot listener: map /command → bash, run them on chat messages
│ ├── pos-communication-telegram-sender # Send Telegram messages/files/links/stickers via Bot API (send, test)
│ ├── pos-config # Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry)
@@ -255,6 +257,8 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
|----------|---------|--------|-------------|
<!-- GEN:START dispatch -->
| ai | gemini | `pos-ai-gemini` | Chat with Google Gemini (ask, chat, models, sessions) |
| communication | matrix-listener | `pos-communication-matrix-listener` | Matrix listener: map /command → bash, run them on room messages |
| communication | matrix-sender | `pos-communication-matrix-sender` | Send messages to a Matrix room via the client-server API (send, test, login) |
| communication | telegram-listener | `pos-communication-telegram-listener` | Telegram bot listener: map /command → bash, run them on chat messages |
| communication | telegram-sender | `pos-communication-telegram-sender` | Send Telegram messages/files/links/stickers via Bot API (send, test) |
| | config | `pos-config` | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |
@@ -327,7 +331,7 @@ source "$(dirname "$0")/../lib/common.sh"
**Scripts that do NOT source common.sh** (self-contained):
<!-- GEN:START selfcontained -->
`pos`, `pos-communication-telegram-listener`, `pos-communication-telegram-sender`, `pos-network-checkport`, `pos-network-hotspot`, `pos-network-ip`, `pos-network-scan`, `pos-ssh-load-keys`, `pos-system-firewall`.
`pos`, `pos-communication-matrix-listener`, `pos-communication-matrix-sender`, `pos-communication-telegram-listener`, `pos-communication-telegram-sender`, `pos-network-checkport`, `pos-network-hotspot`, `pos-network-ip`, `pos-network-scan`, `pos-ssh-load-keys`, `pos-system-firewall`.
<!-- GEN:END selfcontained -->
---
@@ -562,8 +566,10 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
| `bin/flag-clear` | 21 | Unset a flag |
| `features/autostart.sh` | 14 | Boot-time feature (moved from `bin/`, flag-gated service) |
<!-- GEN:START filetable -->
| `bin/pos` | 280 | CLI dispatcher with smart arg matching + logging + category help |
| `bin/pos` | 286 | CLI dispatcher with smart arg matching + logging + category help |
| `bin/pos-ai-gemini` | 311 | Chat with Google Gemini (ask, chat, models, sessions) |
| `bin/pos-communication-matrix-listener` | 565 | Matrix listener: map /command → bash, run them on room messages |
| `bin/pos-communication-matrix-sender` | 214 | Send messages to a Matrix room via the client-server API (send, test, login) |
| `bin/pos-communication-telegram-listener` | 563 | Telegram bot listener: map /command → bash, run them on chat messages |
| `bin/pos-communication-telegram-sender` | 221 | Send Telegram messages/files/links/stickers via Bot API (send, test) |
| `bin/pos-config` | 80 | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |
@@ -591,7 +597,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
| `bin/pos-system-nfs-server` | 134 | Manage the NFS kernel server (status, share/unshare exports, enable/disable) |
| `bin/pos-tree` | 112 | Show the pos CLI command tree: categories, commands, and subcommands |
| `bin/pos-usb-server` | 218 | USB Redirector server control (--ls, --share; prompts when args omitted) |
| `completions/pos.bash` | 286 | Dynamic bash completion |
| `completions/pos.bash` | 288 | Dynamic bash completion |
<!-- GEN:END filetable -->
| `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |
DOC/HOWTO.md
+8 -3
View File
@@ -17,7 +17,7 @@ authoritative one-line reference (every command + flag), see
| `pos system event-trigger` | Threshold-rule monitors that alert on crossing | [event-trigger](howto/event-trigger.md) |
| `pos ssh` | Load keys into the agent | [ssh](howto/ssh.md) |
| `pos usb` | Share USB devices over the network | [usb](howto/usb.md) |
| `pos communication` | Send Telegram messages/files/alerts | [communication](howto/communication.md) |
| `pos communication` | Send Telegram/Matrix messages & alerts, /command listeners | [communication](howto/communication.md) |
| `pos entertainment` | Scheduled auto-messages from public APIs | [entertainment](howto/entertainment.md) |
Every tool is `bin/pos-<category>-<command>`; run `pos <category> --help` to
@@ -36,6 +36,7 @@ templates (without overwriting an existing file):
| File | Used by | Keys |
|------|---------|------|
| `telegram.env` | `pos communication telegram sender` / `listener`, everything that alerts | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` |
| `matrix.env` | `pos communication matrix sender` / `listener` | `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_ROOM_ID` |
| `notify.env` | `lib/notify.sh` (all alerting) | `NOTIFY_PLATFORM` (e.g. `telegram,matrix`) |
| `system.env` | `pos system health`, `pos system backup` | `BACKUP_SERVICE_ROOTS`, `HEALTH_BACKUP_MAX_AGE_DAYS` |
| `compose.env` | `pos docker compose` | `TS_AUTHKEY`, `TZ`, `DNS_SERVER`, `SERVICES_BASE` |
@@ -44,6 +45,8 @@ templates (without overwriting an existing file):
```bash
pos config telegram # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
pos config matrix # set MATRIX_HOMESERVER / MATRIX_ROOM_ID, then:
pos communication matrix sender login --user @you:example.org # fetch an access token
pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75
```
@@ -58,8 +61,10 @@ platform is configured it warns and never breaks the calling tool.
NOTIFY_PLATFORM=telegram # comma-separated to send to all
```
Adding a platform later (e.g. Matrix/Synapse) = create `bin/pos-communication-<p>`
implementing `send <value> [--markdown]` and list it. See
Ship with `telegram` and `matrix` — add both to `NOTIFY_PLATFORM` to fan out
alerts (Matrix needs `pos config matrix` + a `login`-fetched token first).
Adding another platform = create `bin/pos-communication-<p>` implementing
`send <value> [--markdown]` and list it. See
[DOC/DEV.md → Alerting](DEV.md) for the contract.
### Scheduling
DOC/POS.md
+27 -1
View File
@@ -76,7 +76,7 @@ Category-less tools (`config`, `tree`) live outside any category and are documen
Precedence: `--model` flag > `AI_GEMINI_MODEL` env > config file > `gemini-2.5-flash`. `postinstall.sh` copies the repo's `config/ai.env` template to `~/.config/linux_post_install/ai.env` on install (no clobber). Dependencies: `curl` + `jq` (both in `preinstall.sh` PACKAGES).
**Telegram bridge:** the Telegram listener forwards non-command messages starting with `ai ` (case-insensitive) to `pos ai gemini ask` and replies with the model's answer — see [communication → listener](#communication).
**Messaging bridges:** the Telegram and Matrix listeners forward non-command messages starting with `ai ` (case-insensitive) to `pos ai gemini ask` and reply with the model's answer — see [communication → listener](#communication). The Telegram bridge uses one session per chat (`telegram-<chat id>`), the Matrix bridge one per room (`matrix-<room>`).
### network
@@ -226,6 +226,8 @@ Subcommands that need input prompt interactively when args are omitted.
|---------|------|---------|---------------|
| `pos communication telegram sender send "text"` | `bin/pos-communication-telegram-sender` | Send a message, link, or media file (auto-detects the type) to a Telegram chat via the Bot API | Token + chat ID from `~/.config/linux_post_install/telegram.env` (`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, chmod 600). Precedence: `--token`/`--chat-id` flags > env > config file |
| `pos communication telegram listener` | `bin/pos-communication-telegram-listener` | Telegram bot listener: map `/command` → bash commands and run them from chat; interactive editor for the map | Same `telegram.env` (the bot is the owner, `TELEGRAM_CHAT_ID`). Map lives in `~/.config/linux_post_install/telegram_commands.env` (`/cmd=bash command` lines, chmod 600) |
| `pos communication matrix sender send "text"` | `bin/pos-communication-matrix-sender` | Send a text message (plain or `--markdown`) to a Matrix room via the client-server API; also `login` (password → access token) and `test` | Homeserver + room from `~/.config/linux_post_install/matrix.env` (`MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_ROOM_ID`, chmod 600, secrets masked by `pos config matrix`). Precedence: `--room` flag > env > config file |
| `pos communication matrix listener` | `bin/pos-communication-matrix-listener` | Matrix listener: map `/command` → bash commands and run them from room messages; interactive editor for the map | Same `matrix.env` (reacts to `MATRIX_USER_ID`'s own messages; watches `MATRIX_ROOM_ID` or all joined rooms). Map lives in `~/.config/linux_post_install/matrix_commands.env` (`/cmd=bash command` lines, chmod 600) |
`pos communication telegram sender` in detail:
@@ -259,6 +261,30 @@ The map file is re-read for every message — edits apply without a restart. The
Map entries may carry an optional **description** shown in the bot's `/` menu: `/cmd::short description=bash command` (the description falls back to the bash command, truncated to ~40 chars, when omitted). After every add/edit/remove the command list is pushed to the bot via `setMyCommands`, so the menu stays in sync; an empty map clears the menu. Telegram only registers lowercase `[a-z0-9_]` names (1–32 chars) — commands like `/Status` or `/my-cmd` are skipped from the menu with a warning but still resolve when typed.
`pos communication matrix sender` in detail:
| Command | Behavior |
|---------|----------|
| `pos communication matrix sender send "text"` | PUTs an `m.room.message` (`m.text`) to the homeserver's client-server API v3 (60s timeout); prints `[+] m.text sent to room <room>` or fails with a nonzero exit. Room id/alias is URL-encoded automatically; a unique transaction id (`<timestamp>ns`) is generated per message |
| `pos communication matrix sender send "text" --markdown` | Sends with `format: org.matrix.custom.html` — a best-effort markdown → HTML conversion (`**bold**`, `__bold__`, `*em*`, `_em_`, `` `code` ``, ``` ```fences``` ``, `~~strike~~`, `[link](url)`, headers, list items). Deliberately simple; it never fails the send |
| `pos communication matrix sender send "text" --room <id\|alias>` | One-shot override of the room for this send only (e.g. `--room '#ops:example.org'`) |
| `pos communication matrix sender login --user <@id>` | Prompts (masked) for the account password, POSTs `m.login.password` to `/login`, and saves the returned `access_token` + `user_id` to `matrix.env` |
| `pos communication matrix sender test` | Sends a canned test message (`Test message from pos <timestamp>`) using the current config |
The access token is a secret — it is stored only in `~/.config/linux_post_install/matrix.env` and never in the repo. `pos config matrix` edits `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (masked), `MATRIX_USER_ID`, `MATRIX_ROOM_ID`. Requires network access to your homeserver. The sender implements the `lib/notify.sh` sender contract, so `matrix` can be added to `NOTIFY_PLATFORM` for multi-platform alerting.
`pos communication matrix listener` in detail:
| Command | Behavior |
|---------|----------|
| `pos communication matrix listener` | Interactive editor for the `/command` → bash map (`a`dd / `e`dit / `r`emove / `t`est / `q`uit); test-runs run `bash -n` first and may execute the command live |
| `pos communication matrix listener --status` | Shows service state (running/autostart), config + map file paths, and the mapped commands |
| `pos communication matrix listener --enable` | Installs + starts a systemd **user** service (`pos-matrix-listener.service`); the daemon long-polls `/sync` and runs mapped commands |
| `pos communication matrix listener --disable` | Stops, disables, and removes the service |
| `pos communication matrix listener --run` | Run the polling loop in the foreground (what the service executes) |
The daemon long-polls `/sync` (30s timeout, per-sync `since` token, compact filter that drops presence/account_data/device noise and only requests `m.room.message` timeline events). It reacts only to messages **from `MATRIX_USER_ID`** (your own account — resolved via `/account/whoami` if unset); a `MATRIX_ROOM_ID` restricts it to one room, otherwise every joined room is watched. `/` and `!` prefixes both resolve (`!status` = `/status`). `/help` lists mapped commands; an unmapped command replies "Unknown command". Non-command text starting with `ai ` (case-insensitive, e.g. `ai what is Nvidia`) is forwarded to Gemini via `pos ai gemini ask` with a per-room session (`matrix-<room>`; `ai /reset` clears it) and the answer is replied verbatim with markdown stripped. Replies are sent as `m.text` threaded with `m.in_reply_to` on your message. Commands run as your user via `timeout 60 bash -c "…"` (stdout + stderr are replied, truncated to ~3800 chars; empty output → `OK`; non-zero exit is prefixed with `exit <rc>`), so `sudo` inside them needs a NOPASSWD rule. A map value prefixed with `@quiet ` runs the command but does NOT reply — for commands that already send their own notification (e.g. `/status=@quiet pos system health --send`). Map lines may carry a `/cmd::description=…` description. `--enable` warns if linger is off — the service stops when you log out unless you run `sudo loginctl enable-linger $(whoami)`.
### entertainment
**File:** `bin/pos-entertainment-send`
DOC/howto/communication.md
+98 -9
View File
@@ -1,16 +1,18 @@
# How-To: `pos communication`
Telegram messaging and alerts. Tools: `telegram-sender`, `telegram-listener`,
`matrix`.
Messaging and alerts over Telegram and Matrix. Tools: `telegram-sender`,
`telegram-listener`, `matrix-sender`, `matrix-listener`.
| Tool | What it does |
|------|--------------|
| `pos communication telegram sender` | Send messages/files/links/stickers, test, config (token + chat id) |
| `pos communication telegram listener` | Bot listener: map `/command` → bash and run it from chat (systemd user daemon) |
| `pos communication matrix` | Matrix/Synapse sender (extensible; not yet implemented) |
| `pos communication matrix sender` | Send messages to a Matrix room via the client-server API (send, test, login) |
| `pos communication matrix listener` | Matrix listener: map `/command` → bash and run it from room messages (systemd user daemon) |
`telegram-sender` is the workhorse: it backs the whole **notify system** —
health digests, backup alerts, firewall changes — and can be used directly.
`matrix-sender` plugs into the same system as a second platform.
---
@@ -121,20 +123,107 @@ NOTIFY_PLATFORM=telegram # default; comma-separated to fan out to all
```
- `notify_send "msg"` → delivers to every platform in `NOTIFY_PLATFORM`
(current senders: `telegram`).
(current senders: `telegram`, `matrix`).
- **Silent-fail:** no platform configured → one WARN line, exit 0, never
breaks the calling tool.
- New platform (e.g. Matrix): implement `bin/pos-communication-<p> send
- New platform: implement `bin/pos-communication-<p> send
<value> [--markdown]`, then list it in `NOTIFY_PLATFORM`. Details:
[DOC/DEV.md → Alerting](../DEV.md).
---
## `pos communication matrix`
## `pos communication matrix sender`
Sender contract exists (`send <value> [--markdown]`) and the dispatcher routes
to it, but no implementation ships yet. When present, add `matrix` to
`NOTIFY_PLATFORM` and configure it via `pos communication matrix config set …`.
Send plain-text (or markdown-formatted) messages to a Matrix room via the
homeserver's client-server API (v3). No bot is needed — it uses a regular
account's access token.
### One-time setup
```bash
pos config matrix
# set MATRIX_HOMESERVER (https://matrix.example.org) and MATRIX_ROOM_ID
# (room id or alias like #ops:example.org), then grab a token:
pos communication matrix sender login --user @you:example.org
# password is prompted (masked) — access token + user id are saved
pos communication matrix sender test
# config lives in ~/.config/linux_post_install/matrix.env (chmod 600)
```
`login` calls the homeserver's password endpoint and stores the resulting
access token in `matrix.env` (masked by `pos config matrix`). Tokens from any
Matrix client (Element, `synctl`…) work too — set `MATRIX_ACCESS_TOKEN`
directly. Requires network access to your homeserver.
### Send
```bash
pos communication matrix sender send "Backup finished" # plain text
pos communication matrix sender send --markdown "**bold** ok" # org.matrix.custom.html
pos communication matrix sender send "hi" --room '#ops:example.org' # one-shot override
pos communication matrix sender test # canned test message
```
`--markdown` sends with `org.matrix.custom.html` (best-effort markdown →
HTML: `**bold**`, `` `code` ``, links, headers, lists). Room ids and aliases
are URL-encoded automatically.
**Troubleshooting:**
- "No access token" → run `pos communication matrix sender login` first.
- Login fails → is the homeserver URL right (`pos config matrix`) and is the
account password correct? Homeservers may require the full
`@user:example.org` id.
- Nothing arrives → the room id/alias must exist and the account must be a
member. Public aliases like `#pos:example.org` work when the account has
joined.
---
## `pos communication matrix listener`
Turns any room you're in into a remote control for your server: message your
own account a `/command` and the mapped bash runs.
```bash
pos communication matrix listener # edit the /command → bash map
pos communication matrix listener --status # service state + mapped commands
pos communication matrix listener --enable # install the systemd user daemon
pos communication matrix listener --disable # remove it
```
- **Map file:** `~/.config/linux_post_install/matrix_commands.env` (chmod 600),
one `/cmd=bash command` per line — re-read on every message, so edits apply
instantly. Example:
```
/status=@quiet pos system health --send
/temp=sensors | grep -i 'Tctl\|package id 0'
/update=cd /path/to/repo && git pull
```
- **Self-messaging:** the listener reacts to messages **from your own user id**
(`MATRIX_USER_ID`) — in practice that means a second device (or another
account) sending the commands. If `MATRIX_ROOM_ID` is set it only watches
that room, otherwise every room you've joined. `/` and `!` both work
(`!status` = `/status`). `/help` lists mapped commands; unknown → "Unknown
command".
- **Runs as you:** mapped commands execute as your user with a 60s timeout,
stdout + stderr are replied to the room as a thread reply to your message
(truncated ~3800 chars; empty → `OK`). `sudo` inside a command needs a
NOPASSWD rule.
- **`@quiet` prefix:** a map value starting with `@quiet ` runs the command but
does NOT reply — for commands that already send their own notification.
- **`ai …` bridge:** non-command messages starting with `ai ` are answered by
`pos ai gemini` (per-room memory session; `ai /reset` clears it) — replying
with the model's answer, markdown stripped.
- **Daemon lifecycle:** the service is a systemd **user** unit; it stops at
logout unless you enable linger: `sudo loginctl enable-linger $(whoami)`.
`--enable` prints this warning if linger is off.
**Troubleshooting:**
- Doesn't answer → check the service with
`systemctl --user status pos-matrix-listener.service`; the daemon logs to
`~/.local/share/linux_post_install/logs/pos.log`.
- "Unknown command" → send `/help` for the mapped list.
- Needs `jq` (in preinstall PACKAGES).
---