better-dsh 0.2.5-c → 0.2.5-e

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/irc.md

@@ -1,78 +0,0 @@
-# IRC
-
-The IRC adapter connects Hermes to any IRC server and relays messages between an IRC channel (or direct messages) and the agent. It speaks the IRC protocol over Python's stdlib `asyncio` — **no external dependencies, no SDK, no daemon**. It works with public networks like [Libera.Chat](https://libera.chat/) and any self-hosted ircd.
-
-IRC is plain text: there is no voice, image, file, thread, reaction, typing, or streaming support — replies are sent as `PRIVMSG` lines, with long messages split to fit the IRC line limit.
-
-> Run `hermes gateway setup` and pick **IRC** for a guided walk-through.
-
-## Prerequisites
-
-- An IRC server to connect to (e.g. `irc.libera.chat`)
-- A channel to join (e.g. `#hermes`) — comma-separate to join several
-- A nickname for the bot (default: `hermes-bot`)
-- Optional: a registered nick + NickServ password if your network requires identification
-
-## Configure Hermes
-
-You can configure IRC two ways — environment variables (for a quick env-only setup) or the `gateway` block in `~/.hermes/config.yaml`.
-
-### Option A — config.yaml
-
-```yaml
-gateway:
-  platforms:
-    irc:
-      enabled: true
-      extra:
-        server: irc.libera.chat
-        port: 6697
-        nickname: hermes-bot
-        channel: "#hermes"
-        use_tls: true
-        server_password: ""       # optional server password
-        nickserv_password: ""     # optional NickServ identification
-        allowed_users: []         # empty = allow all, or list of nicks
-        max_message_length: 450   # IRC line limit (safe default)
-```
-
-### Option B — environment variables
-
-| Variable | Required | Description |
-|----------|:--------:|-------------|
-| `IRC_SERVER` | ✅ | IRC server hostname (e.g. `irc.libera.chat`) |
-| `IRC_CHANNEL` | ✅ | Channel(s) to join — comma-separate for multiple |
-| `IRC_NICKNAME` | ✅ | Bot nickname (default: `hermes-bot`) |
-| `IRC_PORT` | — | Server port (default: `6697` with TLS, `6667` without) |
-| `IRC_USE_TLS` | — | Use TLS (`true`/`false`; default `true` on port 6697) |
-| `IRC_SERVER_PASSWORD` | — | Server password for the `PASS` command |
-| `IRC_NICKSERV_PASSWORD` | — | NickServ password for automatic IDENTIFY on connect |
-| `IRC_ALLOWED_USERS` | — | Comma-separated nicks allowed to talk to the bot |
-| `IRC_ALLOW_ALL_USERS` | — | Allow anyone in the channel to talk to the bot (dev only) |
-| `IRC_HOME_CHANNEL` | — | Channel for cron / notification delivery (defaults to `IRC_CHANNEL`) |
-
-## Access control
-
-By default, only nicks listed in `allowed_users` (or `IRC_ALLOWED_USERS`) may talk to the bot. Leave the list empty **and** set `IRC_ALLOW_ALL_USERS=true` to let anyone in the channel chat with Hermes — useful for testing, but not recommended on public networks since IRC nicks are not authenticated unless the network enforces NickServ.
-
-If your network registers nicks, set `IRC_NICKSERV_PASSWORD` (or `nickserv_password`) so the bot identifies to NickServ on connect and keeps its registered nick.
-
-## Channels vs. DMs
-
-- Messages in a joined channel are treated as a **group** conversation.
-- Private messages to the bot are treated as **direct messages**.
-
-Cron jobs and notifications are delivered to the **home channel** — `IRC_HOME_CHANNEL` if set, otherwise the first `IRC_CHANNEL`.
-
-## Run the gateway
-
-```bash
-hermes gateway start
-```
-
-Check status with `hermes gateway status` — IRC connection state is reported there, including for env-only setups.
-
-## Notes
-
-- Long agent replies are automatically split into multiple `PRIVMSG` lines to stay within the IRC line limit (`max_message_length`, default 450 bytes after protocol overhead).
-- The adapter acquires a scoped credential lock per server+nick, so two Hermes profiles won't fight over the same IRC identity.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/line.md

@@ -1,201 +0,0 @@
----
-sidebar_position: 17
-title: "LINE"
-description: "Set up Hermes Agent as a LINE Messaging API bot"
----
-
-# LINE Setup
-
-Run Hermes Agent as a [LINE](https://line.me/) bot via the official LINE Messaging API. The adapter lives as a bundled platform plugin under `plugins/platforms/line/` — no core edits, just enable it like any other platform.
-
-LINE is the dominant messaging app in Japan, Taiwan, and Thailand. If your users live there, this is how they reach you.
-
-> Run `hermes gateway setup` and pick **LINE** for a guided walk-through.
-
-## How the bot responds
-
-| Context | Behavior |
-|---------|----------|
-| **1:1 chat** (`U` IDs) | Responds to every message |
-| **Group chat** (`C` IDs) | Responds when the group is on the allowlist |
-| **Multi-user room** (`R` IDs) | Responds when the room is on the allowlist |
-
-Inbound text, images, audio, video, files, stickers, and locations are all handled. Outbound text uses the **free reply token first** (single-use, ~60s window) and falls back to the metered Push API when the token has expired.
-
----
-
-## Step 1: Create a LINE Messaging API channel
-
-1. Go to the [LINE Developers Console](https://developers.line.biz/console/).
-2. Create a Provider, then under it a **Messaging API** channel.
-3. From the channel's **Basic settings** tab, copy the **Channel secret**.
-4. From the **Messaging API** tab, scroll to **Channel access token (long-lived)** and click **Issue**. Copy the token.
-5. In the **Messaging API** tab, also disable **Auto-reply messages** and **Greeting messages** so they don't fight your bot's replies.
-
----
-
-## Step 2: Expose the webhook port
-
-LINE delivers webhooks over public HTTPS. The default port is `8646` — override with `LINE_PORT` if needed.
-
-```bash
-# Cloudflare Tunnel (recommended for production — fixed hostname)
-cloudflared tunnel --url http://localhost:8646
-
-# ngrok (good for dev)
-ngrok http 8646
-
-# devtunnel
-devtunnel create hermes-line --allow-anonymous
-devtunnel port create hermes-line -p 8646 --protocol https
-devtunnel host hermes-line
-```
-
-Copy the `https://...` URL — you'll set it as the webhook URL below. **Leave the tunnel running** while testing. For production, set up a fixed Cloudflare named tunnel so the webhook URL doesn't change on restart.
-
----
-
-## Step 3: Configure Hermes
-
-Add to `~/.hermes/.env`:
-
-```env
-LINE_CHANNEL_ACCESS_TOKEN=YOUR_LONG_LIVED_TOKEN
-LINE_CHANNEL_SECRET=YOUR_CHANNEL_SECRET
-
-# Allowlist — at least one of these (or LINE_ALLOW_ALL_USERS=true for dev)
-LINE_ALLOWED_USERS=U1234567890abcdef...           # comma-separated U-prefixed IDs
-LINE_ALLOWED_GROUPS=C1234567890abcdef...          # optional group IDs
-LINE_ALLOWED_ROOMS=R1234567890abcdef...           # optional room IDs
-
-# Required for image / audio / video sends — the public HTTPS base URL
-# the tunnel resolves to.  Without it, send_image/voice/video will refuse.
-LINE_PUBLIC_URL=https://my-tunnel.example.com
-```
-
-Then in `~/.hermes/config.yaml`:
-
-```yaml
-gateway:
-  platforms:
-    line:
-      enabled: true
-```
-
-That's enough — the bundled-plugin scan in `gateway/config.py` automatically picks up `plugins/platforms/line/`. No `Platform.LINE` enum edit, no `_create_adapter` registration.
-
----
-
-## Step 4: Set the webhook URL
-
-Back in the LINE console:
-
-1. Open your channel → **Messaging API** tab.
-2. Under **Webhook settings** → **Webhook URL**, paste `https://<your-tunnel>/line/webhook` (note the `/line/webhook` path — the adapter listens there).
-3. Click **Verify**. LINE pings the URL; you should see a 200.
-4. Toggle **Use webhook** to **On**.
-
----
-
-## Step 5: Run the gateway
-
-```bash
-hermes gateway
-```
-
-The agent log shows:
-
-```
-LINE: webhook listening on * (all interfaces, IPv4+IPv6):8646/line/webhook (public: https://my-tunnel.example.com)
-```
-
-Add the bot as a friend from the LINE app (scan the QR in the channel's **Messaging API** tab) and send it a message.
-
----
-
-## Slow LLM responses
-
-LINE's reply token is single-use and expires roughly 60 seconds after the inbound event. Slow LLMs can't reply in time, which would normally force a paid Push API call.
-
-When the LLM is still running past `LINE_SLOW_RESPONSE_THRESHOLD` seconds (default `45`), the adapter consumes the original reply token to send a **Template Buttons** bubble:
-
-> 🤔 Still thinking. Tap below to fetch the answer when it's ready.
->
-> [ Get answer ]
-
-The user taps **Get answer** when convenient — that postback delivers a *fresh* reply token, which the adapter uses to send the cached answer (still free).
-
-State machine: `PENDING → READY → DELIVERED`, plus `ERROR` for cancelled runs (the orphan PENDING resolves to "Run was interrupted before completion." after `/stop` so the persistent button doesn't loop).
-
-To disable the postback button and always Push-fallback instead:
-
-```env
-LINE_SLOW_RESPONSE_THRESHOLD=0
-```
-
-For the postback flow to fire reliably, suppress chatter that would consume the reply token before the threshold:
-
-```yaml
-# ~/.hermes/config.yaml
-display:
-  interim_assistant_messages: false
-  platforms:
-    line:
-      tool_progress: off
-```
-
----
-
-## Cron / notification delivery
-
-```env
-LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # default delivery target
-```
-
-Cron jobs with `deliver: line` route to `LINE_HOME_CHANNEL`. The adapter ships a standalone Push-only sender so cron jobs work even when cron runs in a separate process from the gateway.
-
----
-
-## Environment variable reference
-
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `LINE_CHANNEL_ACCESS_TOKEN` | yes | — | Long-lived channel access token |
-| `LINE_CHANNEL_SECRET` | yes | — | Channel secret (HMAC-SHA256 webhook verification) |
-| `LINE_HOST` | no | unset (dual-stack: all interfaces, IPv4+IPv6) | Webhook bind host |
-| `LINE_PORT` | no | `8646` | Webhook bind port |
-| `LINE_PUBLIC_URL` | for media | — | Public HTTPS base URL; required for image/voice/video sends |
-| `LINE_ALLOWED_USERS` | one of | — | Comma-separated user IDs (U-prefixed) |
-| `LINE_ALLOWED_GROUPS` | one of | — | Comma-separated group IDs (C-prefixed) |
-| `LINE_ALLOWED_ROOMS` | one of | — | Comma-separated room IDs (R-prefixed) |
-| `LINE_ALLOW_ALL_USERS` | dev only | `false` | Skip allowlist entirely |
-| `LINE_HOME_CHANNEL` | no | — | Default cron / notification delivery target |
-| `LINE_SLOW_RESPONSE_THRESHOLD` | no | `45` | Seconds before the postback button fires (`0` = disabled) |
-| `LINE_PENDING_TEXT` | no | "🤔 Still thinking…" | Bubble text shown alongside the postback button |
-| `LINE_BUTTON_LABEL` | no | "Get answer" | Button label |
-| `LINE_DELIVERED_TEXT` | no | "Already replied ✅" | Reply when an already-delivered button is tapped again |
-| `LINE_INTERRUPTED_TEXT` | no | "Run was interrupted before completion." | Reply when a `/stop` orphan button is tapped |
-| `LINE_EXPIRED_TEXT` | no | "That request has expired — send your message again." | Reply when a button whose cached answer is gone is tapped |
-
----
-
-## Troubleshooting
-
-**"invalid signature" on webhook verify.** The `Channel secret` was copied wrong, or your tunnel rewrote the request body. Verify with `curl -i https://<tunnel>/line/webhook/health` first — that should return `{"status":"ok","platform":"line"}`.
-
-**Bot receives nothing in groups.** Check `LINE_ALLOWED_GROUPS` includes the `C...` group ID. To find a group ID, send a test message and grep `~/.hermes/logs/gateway.log` for `LINE: rejecting unauthorized source` — the rejected source dict has the IDs.
-
-**`send_image` fails with "LINE_PUBLIC_URL must be set".** LINE's Messaging API does not accept binary uploads — images, audio, and video must be reachable HTTPS URLs. Set `LINE_PUBLIC_URL` to the tunnel's public hostname and the adapter will serve files from `/line/media/<token>/<filename>` automatically.
-
-**Postback button never appears.** Either the LLM responded faster than `LINE_SLOW_RESPONSE_THRESHOLD`, or another bubble (tool-progress, streaming) consumed the reply token first. See the suppression block under "Slow LLM responses".
-
-**"already in use by another profile".** The same channel access token is bound to another running Hermes profile. Stop the other gateway or use a separate channel.
-
----
-
-## Limitations
-
-* **Bubble and length caps.** Each LINE text bubble is capped at 5000 characters. Longer responses are smart-chunked at ~4500 characters across up to 5 bubbles per Reply/Push call, splitting on natural boundaries where possible.
-* **No native message editing.** LINE has no edit-message API — streaming responses always send fresh bubbles, never edit prior ones.
-* **No Markdown rendering.** Bold (`**`), italics (`*`), code fences, and headings render as literal characters. The adapter strips them before sending; URLs are preserved (`[label](url)` becomes `label (url)`).
-* **Loading indicator is DM-only.** LINE rejects the chat/loading API for groups and rooms, so the typing indicator only shows in 1:1 chats.