better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/operate-teams-meeting-pipeline.md

@@ -0,0 +1,295 @@
+---
+title: "Operate the Teams Meeting Pipeline"
+description: "Runbook, go-live checklist, and operator worksheet for the Microsoft Teams meeting pipeline"
+---
+
+# Operate the Teams Meeting Pipeline
+
+Use this guide after you have already enabled the feature from [Teams Meetings](/user-guide/messaging/teams-meetings).
+
+This page covers:
+- operator CLI flows
+- routine subscription maintenance
+- failure triage
+- go-live checks
+- rollout worksheet
+
+## Core Operator Commands
+
+### Validate the config snapshot
+
+```bash
+hermes teams-pipeline validate
+```
+
+Use this first after any config change.
+
+### Inspect token health
+
+```bash
+hermes teams-pipeline token-health
+hermes teams-pipeline token-health --force-refresh
+```
+
+Use `--force-refresh` when you suspect stale auth state.
+
+### Inspect subscriptions
+
+```bash
+hermes teams-pipeline subscriptions
+```
+
+### Renew near-expiry subscriptions
+
+```bash
+hermes teams-pipeline maintain-subscriptions
+hermes teams-pipeline maintain-subscriptions --dry-run
+```
+
+### Automating subscription renewal (REQUIRED for production)
+
+**Microsoft Graph subscriptions expire in at most 72 hours.** If nothing renews them, meeting notifications silently stop after 3 days and the pipeline looks "broken." This is the #1 operational failure mode for any Graph-backed integration.
+
+You MUST run `maintain-subscriptions` on a schedule. Pick one of these three options:
+
+#### Option 1: Hermes cron (recommended if you already run the Hermes gateway)
+
+Hermes ships a built-in cron scheduler. The `--no-agent` mode runs a script as the job (rather than using an LLM), and `--script` must point at a file under `~/.hermes/scripts/`. First create the script:
+
+```bash
+mkdir -p ~/.hermes/scripts
+cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF'
+#!/usr/bin/env bash
+exec hermes teams-pipeline maintain-subscriptions
+EOF
+chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh
+```
+
+Then register a script-only cron job that runs every 12 hours (gives 6x headroom against the 72h expiry window):
+
+```bash
+hermes cron create "0 */12 * * *" \
+  --name "teams-pipeline-maintain-subscriptions" \
+  --no-agent \
+  --script maintain-teams-subscriptions.sh \
+  --deliver local
+```
+
+Verify it was registered and inspect the next run time:
+
+```bash
+hermes cron list
+hermes cron status        # scheduler status
+```
+
+#### Option 2: systemd timer (recommended for Linux production deployments)
+
+Create `/etc/systemd/system/hermes-teams-pipeline-maintain.service`:
+
+```ini
+[Unit]
+Description=Hermes Teams pipeline subscription maintenance
+After=network-online.target
+
+[Service]
+Type=oneshot
+User=hermes
+EnvironmentFile=/etc/hermes/env
+ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions
+```
+
+And `/etc/systemd/system/hermes-teams-pipeline-maintain.timer`:
+
+```ini
+[Unit]
+Description=Run Hermes Teams pipeline subscription maintenance every 12 hours
+
+[Timer]
+OnBootSec=5min
+OnUnitActiveSec=12h
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+Enable:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now hermes-teams-pipeline-maintain.timer
+systemctl list-timers hermes-teams-pipeline-maintain.timer
+```
+
+#### Option 3: Plain crontab
+
+```cron
+0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1
+```
+
+Make sure the cron environment has the `MSGRAPH_*` credentials. Simplest fix: source `~/.hermes/.env` at the top of a wrapper script that crontab calls.
+
+#### Verifying renewal is working
+
+After you've set up the schedule, check renewal activity after the first scheduled run:
+
+```bash
+hermes teams-pipeline subscriptions   # should show expirationDateTime advanced
+hermes teams-pipeline maintain-subscriptions --dry-run   # should show "0 expiring soon" most of the time
+```
+
+If you ever see your Graph webhook mysteriously "stop working" after exactly ~72 hours, this is the first thing to check: did the renewal job actually run?
+
+### Inspect recent jobs
+
+```bash
+hermes teams-pipeline list
+hermes teams-pipeline list --status failed
+hermes teams-pipeline show <job-id>
+```
+
+### Replay a stored job
+
+```bash
+hermes teams-pipeline run <job-id>
+```
+
+### Dry-run meeting artifact fetches
+
+```bash
+hermes teams-pipeline fetch --meeting-id <meeting-id>
+hermes teams-pipeline fetch --join-web-url "<join-url>"
+hermes teams-pipeline fetch --join-web-url "<join-url>" --organizer-user-id <entra-user-id>
+```
+
+Pass `--organizer-user-id` (the organizer's Microsoft Entra user ID) to resolve
+through the organizer-scoped `/users/{id}/onlineMeetings` Graph path. This is
+required for Teams `/meet/` short URLs, which Graph rejects on the
+`/communications/onlineMeetings` endpoint. Webhook-driven jobs derive the
+organizer automatically from the notification's `@odata.id`.
+
+## Routine Runbook
+
+### After first setup
+
+Run these in order:
+
+```bash
+hermes teams-pipeline validate
+hermes teams-pipeline token-health --force-refresh
+hermes teams-pipeline subscriptions
+```
+
+Then trigger or wait for a real meeting event and confirm:
+
+```bash
+hermes teams-pipeline list
+hermes teams-pipeline show <job-id>
+```
+
+### Daily or periodic checks
+
+- run `hermes teams-pipeline maintain-subscriptions --dry-run`
+- inspect `hermes teams-pipeline list --status failed`
+- verify the Teams delivery target is still the correct chat or channel
+
+### Before changing webhook URLs or delivery targets
+
+- update the public notification URL or Teams target config
+- run `hermes teams-pipeline validate`
+- renew or recreate affected subscriptions
+- confirm new events land in the expected sink
+
+## Failure Triage
+
+### No jobs are being created
+
+Check:
+- `msgraph_webhook` is enabled
+- the public notification URL points to `/msgraph/webhook`
+- the client state in the subscription matches `MSGRAPH_WEBHOOK_CLIENT_STATE`
+- subscriptions still exist remotely and are not expired
+
+### Jobs stay in retry or fail before summarization
+
+Check:
+- transcript permissions and availability
+- recording permissions and artifact availability
+- `ffmpeg` availability if recording fallback is enabled
+- Graph token health
+
+### Summaries are produced but not delivered to Teams
+
+Check:
+- `platforms.teams.enabled: true`
+- `delivery_mode`
+- `incoming_webhook_url` for webhook mode
+- `chat_id` or `team_id` plus `channel_id` for Graph mode
+- Teams auth config if Graph posting is used
+
+### Duplicate or unexpected replays
+
+Check:
+- whether you manually replayed a job with `hermes teams-pipeline run`
+- whether the sink record already exists for that meeting
+- whether you intentionally enabled a resend path in your local config
+
+## Go-Live Checklist
+
+- [ ] Graph credentials are present and correct
+- [ ] `msgraph_webhook` is enabled and reachable from the public internet
+- [ ] `MSGRAPH_WEBHOOK_CLIENT_STATE` is set and matches subscriptions
+- [ ] transcript subscription is created
+- [ ] recording subscription is created if STT fallback is required
+- [ ] `ffmpeg` is installed if recording fallback is enabled
+- [ ] Teams outbound delivery target is configured and verified
+- [ ] Notion and Linear sinks are configured only if actually needed
+- [ ] `hermes teams-pipeline validate` returns an OK snapshot
+- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds
+- [ ] **`maintain-subscriptions` is scheduled** (Hermes cron, systemd timer, or crontab — see [Automating subscription renewal](#automating-subscription-renewal-required-for-production)). Without this, Graph subscriptions silently expire within 72 hours.
+- [ ] a real end-to-end meeting event has produced a stored job
+- [ ] at least one summary has reached the intended delivery sink
+
+## Delivery-Mode Decision Guide
+
+| Mode | Use when | Tradeoff |
+|------|----------|----------|
+| `incoming_webhook` | you only need simple posting into Teams | simplest setup, less control |
+| `graph` | you need channel or chat posting through Graph | more control, more auth and target config |
+
+## Operator Worksheet
+
+Fill this out before rollout:
+
+| Item | Value |
+|------|-------|
+| Public notification URL | |
+| Graph tenant ID | |
+| Graph client ID | |
+| Webhook client state | |
+| Transcript resource subscription | |
+| Recording resource subscription | |
+| Teams delivery mode | |
+| Teams chat ID or team/channel | |
+| Notion database ID | |
+| Linear team ID | |
+| Store path override, if any | |
+| Owner for daily checks | |
+
+## Change Review Worksheet
+
+Use this before changing the deployment:
+
+| Question | Answer |
+|----------|--------|
+| Are we changing the public webhook URL? | |
+| Are we rotating Graph credentials? | |
+| Are we changing Teams delivery mode? | |
+| Are we moving to a new Teams chat or channel? | |
+| Do subscriptions need to be recreated or renewed? | |
+| Do we need a fresh end-to-end verification run? | |
+
+## Related Docs
+
+- [Teams Meetings setup](/user-guide/messaging/teams-meetings)
+- [Microsoft Teams bot setup](/user-guide/messaging/teams)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/pipe-script-output.md

@@ -0,0 +1,249 @@
+---
+sidebar_position: 12
+title: "Pipe Script Output to Messaging Platforms"
+description: "Send text from any shell script, cron job, CI hook, or monitoring daemon to Telegram, Discord, Slack, Signal, and other platforms using `hermes send`."
+---
+
+# Pipe Script Output to Messaging Platforms
+
+`hermes send` is a small, scriptable CLI that pushes a message to any
+messaging platform Hermes is already configured for. Think of it as a
+cross-platform `curl` for notifications — you don't need a running
+gateway, you don't need an LLM, and you don't need to re-paste bot tokens
+into each of your scripts.
+
+Use it for:
+
+- System monitoring (memory, disk, GPU temp, long-running job finished)
+- CI/CD notifications (deploy done, test failure)
+- Cron scripts that need to ping you with results
+- Quick one-shot messages from a terminal
+- Piping any tool's output anywhere (`make | hermes send --to slack:#builds`)
+
+The command reuses the same credentials and platform adapters that `hermes
+gateway` already uses, so there's no second configuration surface to
+maintain.
+
+---
+
+## Quick Start
+
+```bash
+# Plain text to the home channel for a platform
+hermes send --to telegram "deploy finished"
+
+# Pipe in stdout from anything
+echo "RAM 92%" | hermes send --to telegram:-1001234567890
+
+# Send a file
+hermes send --to discord:#ops --file /tmp/report.md
+
+# Attach a subject/header line
+hermes send --to slack:#eng --subject "[CI] build.log" --file build.log
+
+# Thread target (Telegram topic, Discord thread)
+hermes send --to telegram:-1001234567890:17585 "threaded reply"
+
+# List every configured target
+hermes send --list
+
+# Filter by platform
+hermes send --list telegram
+```
+
+---
+
+## Argument Reference
+
+| Flag | Description |
+|------|-------------|
+| `-t, --to TARGET` | Destination. See [target formats](#target-formats). |
+| `message` (positional) | Message text. Omit to read from `--file` or stdin. |
+| `-f, --file PATH` | Read the body from a file. `--file -` forces stdin. |
+| `-s, --subject LINE` | Prepend a header/subject line before the body. |
+| `-l, --list` | List available targets. Optional positional platform filter. |
+| `-q, --quiet` | No stdout on success (exit code only — ideal for scripts). |
+| `--json` | Emit the raw JSON result of the send. |
+| `-h, --help` | Show the built-in help text. |
+
+### Target Formats
+
+| Format | Example | Meaning |
+|--------|---------|---------|
+| `platform` | `telegram` | Send to the platform's configured home channel |
+| `platform:chat_id` | `telegram:-1001234567890` | Specific numeric chat / group / user |
+| `platform:chat_id:thread_id` | `telegram:-1001234567890:17585` | Specific thread or Telegram forum topic |
+| `platform:#channel` | `discord:#ops` | Human-friendly channel name (resolved against the channel directory) |
+| `platform:+E164` | `signal:+15551234567` | Phone-addressed platforms: Signal, SMS, WhatsApp |
+
+Any platform Hermes ships adapters for works as a target:
+`telegram`, `discord`, `slack`, `signal`, `sms`, `whatsapp`, `matrix`,
+`mattermost`, `feishu`, `dingtalk`, `wecom`, `weixin`, `email`, and
+others.
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Send (or list) succeeded |
+| `1` | Delivery failed at the platform level (auth, permissions, network) |
+| `2` | Usage / argument / config error |
+
+Exit codes follow the standard Unix convention so your scripts can
+branch on them the same way they would on `curl` or `grep`.
+
+---
+
+## Message Body Resolution
+
+`hermes send` resolves the message body in this order:
+
+1. **Positional argument** — `hermes send --to telegram "hi"`
+2. **`--file PATH`** — `hermes send --to telegram --file msg.txt`
+3. **Piped stdin** — `echo hi | hermes send --to telegram`
+
+When stdin is a TTY (no pipe), Hermes does **not** wait for input — you'll
+get a clear usage error instead. This keeps scripts from hanging if they
+accidentally omit the body.
+
+---
+
+## Real-World Examples
+
+### Monitoring: Memory / Disk Alerts
+
+Replace ad-hoc `curl https://api.telegram.org/...` calls in your watchdogs
+with a single portable line:
+
+```bash
+#!/usr/bin/env bash
+ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}')
+if [ "$ram_pct" -ge 85 ]; then
+  hermes send --to telegram --subject "⚠ MEMORY WARNING" \
+    "RAM ${ram_pct}% on $(hostname)"
+fi
+```
+
+Because `hermes send` reuses your Hermes config, the same script works on
+any host where Hermes is installed — no need to export bot tokens into
+each machine's environment manually.
+
+:::tip Don't alert the gateway about itself
+For watchdogs that might fire when the gateway itself is struggling (OOM
+alerts, disk-full alerts), keep using a minimal `curl` call instead of
+`hermes send`. If the Python interpreter can't load because the box is
+thrashing, you still want that alert to go out.
+:::
+
+### CI / CD: Build and Test Results
+
+```bash
+# In .github/workflows/deploy.yml or any CI script
+if ./scripts/deploy.sh; then
+  hermes send --to slack:#deploys "✅ ${CI_COMMIT_SHA:0:7} deployed"
+else
+  tail -n 100 deploy.log | hermes send \
+    --to slack:#deploys --subject "❌ deploy failed"
+  exit 1
+fi
+```
+
+### Cron: Daily Report
+
+```bash
+# Crontab entry
+0 9 * * * /usr/local/bin/generate-metrics.sh \
+  | /home/me/.hermes/bin/hermes send \
+      --to telegram --subject "Daily metrics $(date +%Y-%m-%d)"
+```
+
+### Long-Running Tasks: Ping When Done
+
+```bash
+./train.py --epochs 200 && \
+  hermes send --to telegram "training done" || \
+  hermes send --to telegram "training failed (exit $?)"
+```
+
+### Scripting with `--json` and `--quiet`
+
+```bash
+# Hard-fail a script if delivery fails; don't clutter logs on success
+hermes send --to telegram --quiet "keepalive" || {
+  echo "Telegram delivery failed" >&2
+  exit 1
+}
+
+# Capture the message ID for later editing / threading
+msg_id=$(hermes send --to discord:#ops --json "build started" \
+  | jq -r .message_id)
+```
+
+---
+
+## Does `hermes send` Need the Gateway Running?
+
+**Usually no.** For any bot-token platform — Telegram, Discord, Slack,
+Signal, SMS, WhatsApp Cloud API, and most others — `hermes send` calls
+the platform's REST endpoint directly using credentials from
+`~/.hermes/.env` and `~/.hermes/config.yaml`. It's a standalone subprocess
+that exits as soon as the message is delivered.
+
+A live gateway is only required for **plugin platforms** that rely on a
+persistent adapter connection (for example, a custom plugin that keeps
+a long-lived WebSocket open). In that case you'll get a clear error
+pointing at the gateway; start it with `hermes gateway start` and retry.
+
+---
+
+## Listing and Discovering Targets
+
+Before sending to a specific channel, you can inspect what's available:
+
+```bash
+# Every target across every configured platform
+hermes send --list
+
+# Just Telegram targets
+hermes send --list telegram
+
+# Machine-readable
+hermes send --list --json
+```
+
+The listing is built from `~/.hermes/channel_directory.json`, which the
+gateway refreshes every few minutes while it's running. If you see
+"no channels discovered yet", start the gateway once (`hermes gateway
+start`) so it can populate the cache.
+
+Human-friendly names (`discord:#ops`, `slack:#engineering`) are resolved
+against this cache at send time, so you don't need to memorize numeric
+IDs.
+
+---
+
+## Comparison with Other Approaches
+
+| Approach | Multi-platform | Reuses Hermes creds | Needs gateway | Best for |
+|----------|----------------|---------------------|---------------|----------|
+| `hermes send` | ✅ | ✅ | No (bot-token) | Everything below |
+| Raw `curl` to each platform | Each scripted separately | Manual | No | Critical watchdogs |
+| `cron` job with `--deliver` | ✅ | ✅ | No | Scheduled agent tasks |
+
+`hermes send` is intentionally the simplest possible surface. If you need
+an agent to decide what to say, schedule a cron job — the agent's final
+response is auto-delivered to the configured `deliver:` target (the agent
+no longer fires messages itself). If you need a scheduled run with LLM-generated content,
+use `cronjob(action='create', prompt=...)` with `deliver='telegram:...'`.
+If you just need to pipe a raw string, reach for `hermes send`.
+
+---
+
+## Related
+
+- [Automate Anything with Cron](/guides/automate-with-cron) —
+  scheduled jobs whose output auto-delivers to any platform.
+- [Gateway Internals](/developer-guide/gateway-internals) —
+  the delivery router that `hermes send` shares with cron delivery.
+- [Messaging Platform Setup](/user-guide/messaging/) —
+  one-time configuration for each platform.