@poolzin/pool-bot 2026.1.26 → 2026.1.30

package/docs/channels/telegram.md

@@ -101,10 +101,10 @@ group messages, so use admin if you need full visibility.
 - Outbound Telegram text uses `parse_mode: "HTML"` (Telegram’s supported tag subset).
 - Markdown-ish input is rendered into **Telegram-safe HTML** (bold/italic/strike/code/links); block elements are flattened to text with newlines/bullets.
 - Raw HTML from models is escaped to avoid Telegram parse errors.
-- If Telegram rejects the HTML payload, Clawdbot retries the same message as plain text.
+- If Telegram rejects the HTML payload, Pool Bot retries the same message as plain text.
 
 ## Commands (native + custom)
-Clawdbot registers native commands (like `/status`, `/reset`, `/model`) with Telegram’s bot menu on startup.
+Pool Bot registers native commands (like `/status`, `/reset`, `/model`) with Telegram’s bot menu on startup.
 You can add custom commands to the menu via config:
 
 ```json5
@@ -128,7 +128,7 @@ You can add custom commands to the menu via config:
 More help: [Channel troubleshooting](/channels/troubleshooting).
 
 Notes:
-- Custom commands are **menu entries only**; Clawdbot does not implement them unless you handle them elsewhere.
+- Custom commands are **menu entries only**; Pool Bot does not implement them unless you handle them elsewhere.
 - Command names are normalized (leading `/` stripped, lowercased) and must match `a-z`, `0-9`, `_` (1–32 chars).
 - Custom commands **cannot override native commands**. Conflicts are ignored and logged.
 - If `commands.native` is disabled, only custom commands are registered (or cleared if none).
@@ -202,13 +202,13 @@ Forward any message from the group to `@userinfobot` or `@getidsbot` on Telegram
 
 **Tip:** For your own user ID, DM the bot and it will reply with your user ID (pairing message), or use `/whoami` once commands are enabled.
 
-**Privacy note:** `@userinfobot` is a third-party bot. If you prefer, add the bot to the group, send a message, and use `clawdbot logs --follow` to read `chat.id`, or use the Bot API `getUpdates`.
+**Privacy note:** `@userinfobot` is a third-party bot. If you prefer, add the bot to the group, send a message, and use `poolbot logs --follow` to read `chat.id`, or use the Bot API `getUpdates`.
 
 ## Config writes
 By default, Telegram is allowed to write config updates triggered by channel events or `/config set|unset`.
 
 This happens when:
-- A group is upgraded to a supergroup and Telegram emits `migrate_to_chat_id` (chat ID changes). Clawdbot can migrate `channels.telegram.groups` automatically.
+- A group is upgraded to a supergroup and Telegram emits `migrate_to_chat_id` (chat ID changes). Pool Bot can migrate `channels.telegram.groups` automatically.
 - You run `/config set` or `/config unset` in a Telegram chat (requires `commands.config: true`).
 
 Disable with:
@@ -219,7 +219,7 @@ Disable with:
 ```
 
 ## Topics (forum supergroups)
-Telegram forum topics include a `message_thread_id` per message. Clawdbot:
+Telegram forum topics include a `message_thread_id` per message. Pool Bot:
 - Appends `:topic:<threadId>` to the Telegram group session key so each topic is isolated.
 - Sends typing indicators and replies with `message_thread_id` so responses stay in the topic.
 - General topic (thread id `1`) is special: message sends omit `message_thread_id` (Telegram rejects it), but typing indicators still include it.
@@ -227,7 +227,7 @@ Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 - Topic-specific configuration is available under `channels.telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).
 - Topic configs inherit group settings (requireMention, allowlists, skills, prompts, enabled) unless overridden per topic.
 
-Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.
+Private chats can include `message_thread_id` in some edge cases. Pool Bot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.
 
 ## Inline Buttons
 
@@ -310,15 +310,15 @@ Use the global setting when all Telegram bots/accounts should behave the same. U
 ### DM access
 - Default: `channels.telegram.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
 - Approve via:
-  - `clawdbot pairing list telegram`
-  - `clawdbot pairing approve telegram <CODE>`
+  - `poolbot pairing list telegram`
+  - `poolbot pairing approve telegram <CODE>`
 - Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
 - `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID. The wizard accepts `@username` and resolves it to the numeric ID when possible.
 
 #### Finding your Telegram user ID
 Safer (no third-party bot):
 1) Start the gateway and DM your bot.
-2) Run `clawdbot logs --follow` and look for `from.id`.
+2) Run `poolbot logs --follow` and look for `from.id`.
 
 Alternate (official Bot API):
 1) DM your bot.
@@ -363,7 +363,7 @@ Controlled by `channels.telegram.replyToMode`:
 
 ## Audio messages (voice vs file)
 Telegram distinguishes **voice notes** (round bubble) from **audio files** (metadata card).
-Clawdbot defaults to audio files for backward compatibility.
+Pool Bot defaults to audio files for backward compatibility.
 
 To force a voice note bubble in agent replies, include this tag anywhere in the reply:
 - `[[audio_as_voice]]` — send audio as a voice note instead of a file.
@@ -383,9 +383,136 @@ For message tool sends, set `asVoice: true` with a voice-compatible audio `media
 }
 ```
 
+## Stickers
+
+Pool Bot supports receiving and sending Telegram stickers with intelligent caching.
+
+### Receiving stickers
+
+When a user sends a sticker, Pool Bot handles it based on the sticker type:
+
+- **Static stickers (WEBP):** Downloaded and processed through vision. The sticker appears as a `<media:sticker>` placeholder in the message content.
+- **Animated stickers (TGS):** Skipped (Lottie format not supported for processing).
+- **Video stickers (WEBM):** Skipped (video format not supported for processing).
+
+Template context field available when receiving stickers:
+- `Sticker` — object with:
+  - `emoji` — emoji associated with the sticker
+  - `setName` — name of the sticker set
+  - `fileId` — Telegram file ID (send the same sticker back)
+  - `fileUniqueId` — stable ID for cache lookup
+  - `cachedDescription` — cached vision description when available
+
+### Sticker cache
+
+Stickers are processed through the AI's vision capabilities to generate descriptions. Since the same stickers are often sent repeatedly, Pool Bot caches these descriptions to avoid redundant API calls.
+
+**How it works:**
+
+1. **First encounter:** The sticker image is sent to the AI for vision analysis. The AI generates a description (e.g., "A cartoon cat waving enthusiastically").
+2. **Cache storage:** The description is saved along with the sticker's file ID, emoji, and set name.
+3. **Subsequent encounters:** When the same sticker is seen again, the cached description is used directly. The image is not sent to the AI.
+
+**Cache location:** `~/.poolbot/telegram/sticker-cache.json`
+
+**Cache entry format:**
+```json
+{
+  "fileId": "CAACAgIAAxkBAAI...",
+  "fileUniqueId": "AgADBAADb6cxG2Y",
+  "emoji": "👋",
+  "setName": "CoolCats",
+  "description": "A cartoon cat waving enthusiastically",
+  "cachedAt": "2026-01-15T10:30:00.000Z"
+}
+```
+
+**Benefits:**
+- Reduces API costs by avoiding repeated vision calls for the same sticker
+- Faster response times for cached stickers (no vision processing delay)
+- Enables sticker search functionality based on cached descriptions
+
+The cache is populated automatically as stickers are received. There is no manual cache management required.
+
+### Sending stickers
+
+The agent can send and search stickers using the `sticker` and `sticker-search` actions. These are disabled by default and must be enabled in config:
+
+```json5
+{
+  channels: {
+    telegram: {
+      actions: {
+        sticker: true
+      }
+    }
+  }
+}
+```
+
+**Send a sticker:**
+
+```json5
+{
+  "action": "sticker",
+  "channel": "telegram",
+  "to": "123456789",
+  "fileId": "CAACAgIAAxkBAAI..."
+}
+```
+
+Parameters:
+- `fileId` (required) — the Telegram file ID of the sticker. Obtain this from `Sticker.fileId` when receiving a sticker, or from a `sticker-search` result.
+- `replyTo` (optional) — message ID to reply to.
+- `threadId` (optional) — message thread ID for forum topics.
+
+**Search for stickers:**
+
+The agent can search cached stickers by description, emoji, or set name:
+
+```json5
+{
+  "action": "sticker-search",
+  "channel": "telegram",
+  "query": "cat waving",
+  "limit": 5
+}
+```
+
+Returns matching stickers from the cache:
+```json5
+{
+  "ok": true,
+  "count": 2,
+  "stickers": [
+    {
+      "fileId": "CAACAgIAAxkBAAI...",
+      "emoji": "👋",
+      "description": "A cartoon cat waving enthusiastically",
+      "setName": "CoolCats"
+    }
+  ]
+}
+```
+
+The search uses fuzzy matching across description text, emoji characters, and set names.
+
+**Example with threading:**
+
+```json5
+{
+  "action": "sticker",
+  "channel": "telegram",
+  "to": "-1001234567890",
+  "fileId": "CAACAgIAAxkBAAI...",
+  "replyTo": 42,
+  "threadId": 123
+}
+```
+
 ## Streaming (drafts)
 Telegram can stream **draft bubbles** while the agent is generating a response.
-Clawdbot uses Bot API `sendMessageDraft` (not real messages) and then sends the
+Pool Bot uses Bot API `sendMessageDraft` (not real messages) and then sends the
 final reply as a normal message.
 
 Requirements (Telegram Bot API 9.3+):
@@ -420,12 +547,12 @@ Outbound Telegram API calls retry on transient network/429 errors with exponenti
 - Tool: `telegram` with `react` action (`chatId`, `messageId`, `emoji`).
 - Tool: `telegram` with `deleteMessage` action (`chatId`, `messageId`).
 - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
-- Tool gating: `channels.telegram.actions.reactions`, `channels.telegram.actions.sendMessage`, `channels.telegram.actions.deleteMessage` (default: enabled).
+- Tool gating: `channels.telegram.actions.reactions`, `channels.telegram.actions.sendMessage`, `channels.telegram.actions.deleteMessage` (default: enabled), and `channels.telegram.actions.sticker` (default: disabled).
 
 ## Reaction notifications
 
 **How reactions work:**
-Telegram reactions arrive as **separate `message_reaction` events**, not as properties in message payloads. When a user adds a reaction, Clawdbot:
+Telegram reactions arrive as **separate `message_reaction` events**, not as properties in message payloads. When a user adds a reaction, Pool Bot:
 
 1. Receives the `message_reaction` update from Telegram API
 2. Converts it to a **system event** with format: `"Telegram reaction added: {emoji} by {user} on msg {id}"`
@@ -461,28 +588,28 @@ The agent sees reactions as **system notifications** in the conversation history
 ```
 
 **Requirements:**
-- Telegram bots must explicitly request `message_reaction` in `allowed_updates` (configured automatically by Clawdbot)
+- Telegram bots must explicitly request `message_reaction` in `allowed_updates` (configured automatically by Pool Bot)
 - For webhook mode, reactions are included in the webhook `allowed_updates`
 - For polling mode, reactions are included in the `getUpdates` `allowed_updates`
 
 ## Delivery targets (CLI/cron)
 - Use a chat id (`123456789`) or a username (`@name`) as the target.
-- Example: `clawdbot message send --channel telegram --target 123456789 --message "hi"`.
+- Example: `poolbot message send --channel telegram --target 123456789 --message "hi"`.
 
 ## Troubleshooting
 
 **Bot doesn’t respond to non-mention messages in a group:**
 - If you set `channels.telegram.groups.*.requireMention=false`, Telegram’s Bot API **privacy mode** must be disabled.
   - BotFather: `/setprivacy` → **Disable** (then remove + re-add the bot to the group)
-- `clawdbot channels status` shows a warning when config expects unmentioned group messages.
-- `clawdbot channels status --probe` can additionally check membership for explicit numeric group IDs (it can’t audit wildcard `"*"` rules).
+- `poolbot channels status` shows a warning when config expects unmentioned group messages.
+- `poolbot channels status --probe` can additionally check membership for explicit numeric group IDs (it can’t audit wildcard `"*"` rules).
 - Quick test: `/activation always` (session-only; use config for persistence)
 
 **Bot not seeing group messages at all:**
 - If `channels.telegram.groups` is set, the group must be listed or use `"*"`
 - Check Privacy Settings in @BotFather → "Group Privacy" should be **OFF**
 - Verify bot is actually a member (not just an admin with no read access)
-- Check gateway logs: `clawdbot logs --follow` (look for "skipping group message")
+- Check gateway logs: `poolbot logs --follow` (look for "skipping group message")
 
 **Bot responds to mentions but not `/activation always`:**
 - The `/activation` command updates session state but doesn't persist to config
@@ -494,7 +621,7 @@ The agent sees reactions as **system notifications** in the conversation history
 
 **Long-polling aborts immediately on Node 22+ (often with proxies/custom fetch):**
 - Node 22+ is stricter about `AbortSignal` instances; foreign signals can abort `fetch` calls right away.
-- Upgrade to a Clawdbot build that normalizes abort signals, or run the gateway on Node 20 until you can upgrade.
+- Upgrade to a Pool Bot build that normalizes abort signals, or run the gateway on Node 20 until you can upgrade.
 
 **Bot starts, then silently stops responding (or logs `HttpError: Network request ... failed`):**
 - Some hosts resolve `api.telegram.org` to IPv6 first. If your server does not have working IPv6 egress, grammY can get stuck on IPv6-only requests.
@@ -529,6 +656,7 @@ Provider options:
 - `channels.telegram.streamMode`: `off | partial | block` (draft streaming).
 - `channels.telegram.mediaMaxMb`: inbound/outbound media cap (MB).
 - `channels.telegram.retry`: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
+- `channels.telegram.network.autoSelectFamily`: override Node autoSelectFamily (true=enable, false=disable). Defaults to disabled on Node 22 to avoid Happy Eyeballs timeouts.
 - `channels.telegram.proxy`: proxy URL for Bot API calls (SOCKS/HTTP).
 - `channels.telegram.webhookUrl`: enable webhook mode.
 - `channels.telegram.webhookSecret`: webhook secret (optional).
@@ -536,6 +664,7 @@ Provider options:
 - `channels.telegram.actions.reactions`: gate Telegram tool reactions.
 - `channels.telegram.actions.sendMessage`: gate Telegram tool message sends.
 - `channels.telegram.actions.deleteMessage`: gate Telegram tool message deletes.
+- `channels.telegram.actions.sticker`: gate Telegram sticker actions — send and search (default: false).
 - `channels.telegram.reactionNotifications`: `off | own | all` — control which reactions trigger system events (default: `own` when not set).
 - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — control agent's reaction capability (default: `minimal` when not set).
 

package/docs/channels/tlon.md

@@ -5,7 +5,7 @@ read_when:
 ---
 # Tlon (plugin)
 
-Tlon is a decentralized messenger built on Urbit. Clawdbot connects to your Urbit ship and can
+Tlon is a decentralized messenger built on Urbit. Pool Bot connects to your Urbit ship and can
 respond to DMs and group chat messages. Group replies require an @ mention by default and can
 be further restricted via allowlists.
 
@@ -19,13 +19,13 @@ Tlon ships as a plugin and is not bundled with the core install.
 Install via CLI (npm registry):
 
 ```bash
-clawdbot plugins install @clawdbot/tlon
+poolbot plugins install @poolbot/tlon
 ```
 
 Local checkout (when running from a git repo):
 
 ```bash
-clawdbot plugins install ./extensions/tlon
+poolbot plugins install ./extensions/tlon
 ```
 
 Details: [Plugins](/plugin)
@@ -121,7 +121,7 @@ Group authorization (restricted by default):
 
 ## Delivery targets (CLI/cron)
 
-Use these with `clawdbot message send` or cron delivery:
+Use these with `poolbot message send` or cron delivery:
 
 - DM: `~sampel-palnet` or `dm/~sampel-palnet`
 - Group: `chat/~host-ship/channel` or `group:~host-ship/channel`
@@ -129,5 +129,5 @@ Use these with `clawdbot message send` or cron delivery:
 ## Notes
 
 - Group replies require a mention (e.g. `~your-bot-ship`) to respond.
-- Thread replies: if the inbound message is in a thread, Clawdbot replies in-thread.
+- Thread replies: if the inbound message is in a thread, Pool Bot replies in-thread.
 - Media: `sendMedia` falls back to text + URL (no native upload).

package/docs/channels/troubleshooting.md

@@ -9,8 +9,8 @@ read_when:
 Start with:
 
 ```bash
-clawdbot doctor
-clawdbot channels status --probe
+poolbot doctor
+poolbot channels status --probe
 ```
 
 `channels status --probe` prints warnings when it can detect common channel misconfigurations, and includes small live checks (credentials, some permissions/membership).