polygram 0.1.0 → 0.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "polygram",
+  "version": "0.1.0",
+  "description": "Admin + transcript skills for the polygram Telegram daemon.",
+  "author": {
+    "name": "Ivan Shumkov",
+    "email": "ivan.shumkov@dash.org"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/shumkov/polygram",
+  "repository": "https://github.com/shumkov/polygram"
+}

package/README.md

@@ -101,6 +101,33 @@ on first run (migrations apply automatically) and opens a Unix socket at
 
 For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
 
+## Install as a Claude Code plugin
+
+polygram also ships as a Claude Code plugin — adds admin slash commands
+and bundles the transcript-query skill for use inside your Claude sessions.
+
+```
+/plugin install https://github.com/shumkov/polygram.git
+```
+
+Once installed:
+
+- `/polygram:status` — running bots, IPC health, recent events, one-line verdict
+- `/polygram:logs <bot>` — tail `~/polygram/logs/<bot>.log`
+- `/polygram:pair-code` — walks you through issuing a pairing code (in-band via Telegram)
+- `/polygram:approvals [bot]` — pending and recent tool-approval rows
+
+The bundled **`telegram-history` skill** lets Claude query the transcript
+directly:
+
+```
+"Summarise the Orders topic today" →
+  uses skills/telegram-history to run `recent <chat> --since 24h`
+```
+
+Scope is derived from `process.cwd()`: the skill refuses to run from an
+unmapped directory unless `BRIDGE_ADMIN=1` is set.
+
 ## Configuration
 
 Minimal:

package/commands/approvals.md

@@ -0,0 +1,37 @@
+---
+description: List pending and recent approvals from a polygram bot's DB.
+argument-hint: [bot-name]
+---
+
+Show the operator recent tool-call approvals, gated via the polygram
+`PreToolUse` hook.
+
+If no bot name was given, list configured bots from
+`~/polygram/config.json` and ask which one.
+
+For the chosen `<bot-name>`:
+
+1. **Pending (awaiting a click):**
+   ```
+   sqlite3 ~/polygram/<bot-name>.db "SELECT id, requested_ts, tool_name, substr(tool_input_json, 1, 80) AS preview FROM pending_approvals WHERE status = 'pending' ORDER BY requested_ts DESC LIMIT 20;"
+   ```
+
+2. **Recent (last 24 h, all statuses):**
+   ```
+   sqlite3 ~/polygram/<bot-name>.db "SELECT id, status, decided_by_user, tool_name, substr(tool_input_json, 1, 80) AS preview FROM pending_approvals WHERE requested_ts > strftime('%s', 'now', '-1 day') * 1000 ORDER BY requested_ts DESC LIMIT 20;"
+   ```
+
+3. **Sweep-failed events in the last 7 days** (the sweeper itself dying
+   is an ops alarm):
+   ```
+   sqlite3 ~/polygram/<bot-name>.db "SELECT ts, detail_json FROM events WHERE kind = 'approval-sweep-failed' AND ts > strftime('%s', 'now', '-7 days') * 1000 ORDER BY ts DESC LIMIT 5;"
+   ```
+
+Render two short Markdown tables. For pending rows, note how long they've
+been waiting (`requested_ts` vs now). For resolved rows, show who decided
+and when. Flag anything where `status = 'timeout'` — those tool calls
+were auto-denied because no one acted in time.
+
+If the DB doesn't exist at `~/polygram/<bot-name>.db`, check whether this
+is a pre-cutover install still using a shared `bridge.db`; in that case
+point the operator at `~/polygram/bridge.db` for the same query.

package/commands/logs.md

@@ -0,0 +1,37 @@
+---
+description: Tail the last N lines of a polygram bot's launchd log.
+argument-hint: <bot-name> [lines]
+---
+
+The user wants to see recent logs from a polygram bot.
+
+Arguments:
+- `<bot-name>` — required; the bot whose log to tail (matches `--bot` name,
+  same as the launchd plist suffix `com.polygram.<bot-name>`).
+- `[lines]` — optional; number of trailing lines (default 100).
+
+Default log path is `~/polygram/logs/<bot-name>.log`. If the user uses a
+custom `POLYGRAM_HOME`, ask first.
+
+Steps:
+
+1. Show the last N lines:
+   ```
+   tail -n {lines:-100} ~/polygram/logs/<bot-name>.log
+   ```
+
+2. Scan the output for notable patterns and surface them. Things worth
+   flagging:
+   - `[fatal]` or `Error:` lines
+   - `409, waiting 3s` (Telegram conflict — another grammy instance?)
+   - `poll-stalled` — watchdog event
+   - `approval-sweep-failed` — sweeper died
+   - `telegram-api-error` — delivery failure
+
+3. If the file is empty or missing, check whether the bot is actually
+   loaded (`launchctl list | grep com.polygram.<bot-name>`) and report
+   that distinction — "bot not loaded" vs "bot running but silent".
+
+Respond with:
+- A code fence containing the raw tail (use Markdown triple-backticks)
+- A short plain-English summary of anything notable

package/commands/pair-code.md

@@ -0,0 +1,47 @@
+---
+description: Explain how to issue a polygram pairing code for a new guest user.
+argument-hint: [bot-name]
+---
+
+Explain to the operator how to mint a pairing code.
+
+Pairing codes are issued through Telegram itself — the operator DMs the bot
+from the admin chat. This is intentional: pairing grants cross-chat trust
+and must run as an authenticated user the bot already knows, not as a
+claude-code session.
+
+If a bot name was provided, confirm it's one of the configured bots; if
+not, list configured bots from `~/polygram/config.json` (read-only) so the
+user can pick.
+
+Then tell them to:
+
+1. Open Telegram, go to their admin chat with the bot (the chat whose ID
+   matches `config.bot.adminChatId`).
+
+2. Send:
+   ```
+   /pair-code --ttl 1h --note "Jane — new designer"
+   ```
+   Optional flags: `--chat <chat_id>` to scope the code to a specific chat,
+   `--scope user|chat`, `--ttl 10m|1h|1d`.
+
+3. The bot replies with a code like `K7M2P4VQ`. Share it with the guest
+   through a separate channel.
+
+4. Guest DMs the bot (any chat the bot is in):
+   ```
+   /pair K7M2P4VQ
+   ```
+
+5. Revoke later with:
+   ```
+   /unpair <user_id>
+   ```
+
+Admin commands are gated to the admin chat — `/pair-code` run from any
+other chat returns "admin-only" regardless of `allowConfigCommands`.
+
+If the user asks you to issue the code for them directly from this Claude
+session, politely refuse — explain that pairing is an in-band Telegram
+operation and tell them to run it from the bot DM themselves.

package/commands/status.md

@@ -0,0 +1,40 @@
+---
+description: Show polygram daemon health — running bots, IPC sockets, recent events.
+---
+
+You are asked to report the current health of the polygram Telegram daemon.
+
+Do these checks, in order, using the Bash tool, and summarise the results in
+a short Markdown table (one row per bot):
+
+1. **Which bots are supervised by launchd.** Run:
+   ```
+   launchctl list | grep -i polygram || echo "no LaunchAgents loaded"
+   ```
+   Parse the output. Each line `<PID>\t<exit>\t<label>` is one bot
+   (e.g. `com.polygram.my-bot`). The PID column tells you whether it is
+   running; `-` means loaded but not currently running.
+
+2. **Is each bot's Unix socket alive?** For every bot you identified, run:
+   ```
+   node ~/polygram/scripts/ipc-smoke.js <bot-name>
+   ```
+   Interpret the result:
+   - `ping: {"id":null,"ok":true,"pong":true,"bot":"<bot>"}` → socket alive
+   - `ERR: connect ECONNREFUSED` → socket stale (bridge not actually
+     serving despite plist being loaded)
+   - `ERR: ENOENT` → socket missing (bridge never got that far at boot)
+
+3. **Recent events in each bot's DB.** For every bot, run:
+   ```
+   sqlite3 ~/polygram/<bot>.db "SELECT ts, kind, detail_json FROM events ORDER BY ts DESC LIMIT 5;"
+   ```
+   Call out anything that looks like an error (`-fail`, `-error`,
+   `crashed-mid-send`, `poll-stalled`, `approval-sweep-failed`).
+
+4. **Summarise.** A two-line per-bot summary, plus an overall verdict at
+   the bottom (✅ healthy / ⚠️ degraded / ❌ broken).
+
+If the user's polygram install is not at `~/polygram`, they may have set
+`POLYGRAM_HOME` or a custom path. Ask them to point you at it rather than
+guessing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc-client.js",
   "bin": {
@@ -15,6 +15,8 @@
     "scripts/split-db.js",
     "scripts/ipc-smoke.js",
     "skills/",
+    "commands/",
+    ".claude-plugin/",
     "ops/polygram.plist.example",
     "ops/README.md",
     "config.example.json"