polygram 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Shumkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# polygram
+
+A Telegram daemon for Claude Code that preserves the per-chat session model
+from OpenClaw. Intended primarily as a migration path for users moving
+their Telegram-based ops from OpenClaw to Claude Code.
+
+## Background
+
+OpenClaw ran a Telegram agent with one conversation context per chat.
+Each chat had its own persistent memory; topics in a forum chat could
+optionally carry their own sub-context. The agent, cron scripts, and
+human operators all wrote into a shared transcript.
+
+OpenClaw no longer supports Claude. Migrating to Claude Code loses that
+model unless it's rebuilt. The official `telegram@claude-plugins-official`
+plugin is single-session — one Claude Code process, one bot, one shared
+context across all chats. Third-party Claude Code Telegram bots usually
+share one session across all users of a given bot instance.
+
+`polygram` is the shape that keeps OpenClaw's per-chat-session
+ergonomics while running on top of `claude` CLI.
+
+## What it is
+
+- **One Node process per bot.** Required `--bot <name>` flag. N bots = N
+  processes. No "one process hosts many bots" mode — crash isolation is
+  the point.
+- **Per-chat Claude sessions.** Each chat has its own `claude_session_id`,
+  resumed via `claude --resume`.
+- **Per-topic sessions — opt-in** (`isolateTopics: true` in chat config).
+  Default is shared context across topics, since topics are usually
+  organisational. OpenClaw migrators who used per-topic separation can
+  keep it with one flag.
+- **SQLite transcripts** (WAL, FTS5, numbered migrations, `user_version`).
+- **Write-before-send atomicity.** Outbound messages hit the DB as
+  `pending` before the Telegram call, flip to `sent` or `failed` after.
+  Boot sweep resolves stale `pending` rows from the last crash.
+- **Unix-socket IPC per bot.** Cron jobs and Claude Code approval hooks
+  talk to the bot process over `/tmp/polygram-<bot>.sock`. The bot
+  is the only writer to its own DB.
+- **Inline-keyboard approvals.** Destructive tool calls gate on operator
+  click via Claude Code's `PreToolUse` hook; 5-minute auto-deny.
+- **Voice transcription.** OpenAI Whisper API or local `whisper.cpp`,
+  selectable per bot. Transcriptions land in `messages.text` so FTS
+  finds them.
+- **Content-addressed attachment storage** via Telegram's `file_unique_id`.
+  Same photo forwarded twice = one file on disk.
+- **Prompt-injection hardening.** User text wrapped in `<untrusted-input>`
+  with xml-escape; attributes use `&quot;`. A partner typing
+  `</channel><system>...` sees it as literal text in the prompt.
+- **Pairing codes** for guest onboarding without bridge restart
+  (`/pair-code`, `/pair <CODE>`, `/pairings`, `/unpair`).
+- **Step-level streaming replies** (optional per bot). Telegram message
+  edits on each assistant step as Claude works through tool calls and
+  reasoning.
+
+## Relation to existing projects
+
+| | Session unit | Bots per install | Persistence |
+|---|---|---|---|
+| [`telegram@claude-plugins-official`](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram) | one (bound to an open Claude Code session) | one | session memory only |
+| [`ClaudeBot`](https://github.com/Jeffrey0117/ClaudeBot) | worktree path (≈ one per bot) | many (git worktrees) | `.sessions.json` |
+| [`claudegram`](https://github.com/NachoSEO/claudegram) | chat (+ forum topic) | one | JSON files |
+| **polygram** | chat (+ optional forum topic) | many (per-process) | SQLite WAL + FTS5 |
+
+Practical differences that matter for migration:
+
+- The official plugin dies with `/exit`, so it can't carry scheduled jobs
+  or replace a long-running ops bot.
+- `ClaudeBot` puts many chats on one session per bot. For OpenClaw users
+  this feels wrong — a customer group and an ops group would share
+  memory unless each goes in its own worktree.
+- `claudegram` gets the session model right but serves one bot per
+  install. Running five bots means five copies of the infra.
+- `polygram` lands on the combination: multi-bot (one process per
+  bot) and per-chat/per-topic sessions. Scaling from one bot to many
+  doesn't change the mental model inherited from OpenClaw.
+
+## Install
+
+Requires Node 20+.
+
+```bash
+git clone https://github.com/shumkov/polygram.git
+cd polygram
+npm install
+cp config.example.json config.json
+# edit config.json: tokens from @BotFather, chat IDs, cwds
+```
+
+## Run
+
+```bash
+node bridge.js --bot admin-bot          # one bot, one process
+node bridge.js --bot partner-bot        # another bot, another process
+```
+
+`--bot` is required. Each process creates `<bot>.db` next to `bridge.js`
+on first run (migrations apply automatically) and opens a Unix socket at
+`/tmp/polygram-<bot>.sock`.
+
+For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
+
+## Configuration
+
+Minimal:
+
+```json
+{
+  "bots": {
+    "my-bot": { "token": "..." }
+  },
+  "chats": {
+    "123456789": {
+      "name": "My DM",
+      "bot": "my-bot",
+      "agent": "my-agent",
+      "model": "sonnet",
+      "effort": "low",
+      "cwd": "/Users/me/my-agent"
+    }
+  }
+}
+```
+
+Per-chat flags:
+
+- `isolateTopics: true` — each forum topic gets its own Claude session.
+  Default is shared.
+- `requireMention: true` — group chats only respond to `@botname` or
+  replies to bot messages. Paired users bypass this.
+- `topics: { "<thread_id>": "<name>" }` — human-readable topic labels
+  included in the prompt.
+
+Per-bot flags:
+
+- `allowConfigCommands: true` — enables `/model`, `/effort`, `/pair-code`,
+  `/pairings`, `/unpair`.
+- `streamReplies: true` — live-edit the Telegram message as Claude works.
+- `voice: { enabled, provider: "openai"|"local", ... }` — Whisper
+  transcription settings.
+- `approvals: { adminChatId, timeoutMs, gatedTools, ... }` — which tool
+  calls require an inline-keyboard approval and where to post the card.
+
+See `config.example.json` for the full schema.
+
+## Migrating from OpenClaw
+
+See the design doc (`docs/polygram-design.md`) for the full trust model
+and architectural choices. In practice:
+
+1. Install `polygram`, point chat `cwd` at your migrated agent
+   project.
+2. Copy OpenClaw's per-partner memory directories to their new chat
+   directories if you used them.
+3. For chats where each OpenClaw topic had its own context, set
+   `isolateTopics: true` in chat config.
+4. For cron/scheduled scripts, replace direct Telegram API calls with
+   `tell(bot, method, params, {source})` from `lib/ipc-client`. The
+   bot process writes to the transcript; the script just asks it to send.
+5. Use `scripts/split-db.js` if you're consolidating multiple OpenClaw
+   databases — otherwise per-bot SQLite files start fresh.
+
+## Cron → bot (IPC)
+
+```js
+const { tell } = require('polygram/lib/ipc-client');
+
+await tell('admin-bot', 'sendMessage', {
+  chat_id: '123456789',
+  text: 'Daily inventory report ready.',
+}, { source: 'cron:inventory-report' });
+```
+
+Allowed methods: `sendMessage`, `sendPhoto`, `sendDocument`, `sendSticker`,
+`sendChatAction`, `editMessageText`, `setMessageReaction`. The socket
+server rejects others. Cross-bot sends are rejected (chat must belong
+to the bot on the other end of the socket).
+
+If the bot process is down, the call throws. This is intentional — cron
+failures should surface.
+
+## The `telegram-history` skill
+
+A Claude skill that queries the transcript:
+
+```bash
+node skills/telegram-history/scripts/query.js recent -1000000000001 --since 24h
+node skills/telegram-history/scripts/query.js search "invoice" --user Maria
+node skills/telegram-history/scripts/query.js around --chat -100... --msg-id 12345 --before 10
+```
+
+Bot scope is derived from `process.cwd()` — the skill refuses to run if
+the cwd doesn't match a chat in config, unless `BRIDGE_ADMIN=1` is set.
+With per-bot DBs the skill opens only the current bot's file; in admin
+mode it unions across all `<bot>.db` files.
+
+## Approvals
+
+Config:
+
+```json
+"approvals": {
+  "adminChatId": "123456789",
+  "timeoutMs": 300000,
+  "gatedTools": ["Bash(rm *)", "mcp__*__invoice_create"]
+}
+```
+
+Install the hook at the agent level (`settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash|mcp__*",
+      "hooks": [{
+        "type": "command",
+        "command": "/abs/path/to/polygram/bin/bridge-approval-hook.js"
+      }]
+    }]
+  }
+}
+```
+
+When Claude attempts a matched tool, the hook blocks, the daemon posts
+`[Approve]/[Deny]` buttons to `adminChatId`, and the tool runs (or is
+denied) after the click. Tokens in `callback_data` defeat replay;
+foreign-chat clicks are rejected. Default-deny on IPC error.
+
+## Development
+
+```bash
+npm test        # 336 tests, 72 suites, node:test, no external services
+npm start -- --bot my-bot
+npm run split-db -- --config config.json --dry-run
+npm run ipc-smoke -- my-bot
+```
+
+Layout:
+
+```
+bridge.js                         main daemon
+bin/bridge-approval-hook.js       PreToolUse hook
+lib/                              core modules (db, prompt, telegram,
+                                   process-manager, sessions, history,
+                                   attachments, inbox, voice, approvals,
+                                   pairings, ipc-{server,client},
+                                   session-key, stream-reply, ...)
+migrations/NNN-*.sql              applied at boot, guarded by user_version
+skills/telegram-history/          Claude skill
+ops/                              LaunchAgent plists
+scripts/split-db.js               one-time shared-DB → per-bot migration
+tests/*.test.js                   node:test
+```
+
+## Status and non-goals
+
+- Used in production by the author for a retail ops workflow.
+- No horizontal scale-out. One machine, shared filesystem. If you need
+  bot A in Bangkok and bot B on AWS, swap SQLite for something networked;
+  that's not on the roadmap.
+- Claude Code only. No abstraction over other AIs.
+- macOS LaunchAgent plists included; Linux systemd units are not (easy
+  to adapt).
+- No marketplace plugin wrapper yet. See roadmap.
+
+## Roadmap
+
+- Pairings phase 2: auto-create DM chat entries for paired users in
+  unknown chats.
+- Approvals phase 2: deny-with-reason, per-user quotas.
+- Voice phase 2: `/replay-voice` to re-transcribe with a language hint.
+- `/replay-pending` admin command for crashed-mid-send rows.
+- Marketplace plugin wrapper with slash commands for admin.
+
+## Licence
+
+MIT — see [LICENSE](./LICENSE).
+
+## Acknowledgements
+
+- [grammy](https://grammy.dev) for the Telegram client.
+- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) for the
+  storage layer.
+- OpenClaw for the per-chat session ergonomics this project aims to
+  preserve.

package/bin/bridge-approval-hook.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PreToolUse hook -> bridge daemon approval round-trip.
+ *
+ * Installed into an agent's settings.json:
+ *   { "hooks": { "PreToolUse": [
+ *     { "matcher": "Bash|WebFetch|mcp__*", "hooks": [
+ *       { "type": "command",
+ *         "command": "/Users/YOURNAME/polygram/bin/bridge-approval-hook.js" }
+ *     ]}
+ *   ]}}
+ *
+ * Environment (set by the bridge when spawning Claude):
+ *   BRIDGE_BOT       - bot name owning this session (socket suffix)
+ *   BRIDGE_CHAT_ID   - chat whose message triggered this turn (for the card)
+ *   BRIDGE_TURN_ID   - optional; helps dedupe re-fires on Claude retries
+ *
+ * Contract (Claude Code):
+ *   stdin  JSON: { session_id, hook_event_name: "PreToolUse",
+ *                  tool_name, tool_input, ... }
+ *   stdout JSON reply for PreToolUse: either pass-through (exit 0 empty stdout),
+ *          or a block decision:
+ *     {"hookSpecificOutput": {"hookEventName":"PreToolUse",
+ *                             "permissionDecision":"allow"|"deny"|"ask",
+ *                             "permissionDecisionReason":"..."}}
+ *   Exit codes:
+ *     0 - allow (empty stdout) or structured decision in stdout
+ *     2 - block (deny)
+ *
+ * Failure policy: on IPC error (bridge down, socket missing, timeout) we
+ * deny by default. Better to block a legitimate tool call than to let a
+ * destructive one through when the approver is unreachable.
+ */
+
+const fs = require('fs');
+
+(async () => {
+  const botName = process.env.BRIDGE_BOT;
+  const chatId  = process.env.BRIDGE_CHAT_ID;
+  const turnId  = process.env.BRIDGE_TURN_ID || null;
+
+  if (!botName || !chatId) {
+    deny('bridge-approval-hook: BRIDGE_BOT and BRIDGE_CHAT_ID env vars required');
+    return;
+  }
+
+  let req;
+  try {
+    req = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch (err) {
+    deny(`bad hook input: ${err.message}`);
+    return;
+  }
+  if (req.hook_event_name !== 'PreToolUse') {
+    // Not our event; pass through silently.
+    process.exit(0);
+  }
+
+  // Resolve relative to this hook's own location rather than a hardcoded
+  // absolute path — an absolute-path require is a symlink-swap RCE vector
+  // (anyone who can write to that path gets code execution in-bridge).
+  const path = require('path');
+  const { call, socketPathFor, readSecret } = require(path.join(__dirname, '..', 'lib', 'ipc-client'));
+  let res;
+  try {
+    res = await call({
+      path: socketPathFor(botName),
+      op: 'approval_request',
+      secret: readSecret(botName),
+      payload: {
+        bot_name: botName,
+        chat_id: chatId,
+        turn_id: turnId,
+        tool_name: req.tool_name,
+        tool_input: req.tool_input,
+      },
+    });
+  } catch (err) {
+    deny(`bridge unreachable: ${err.message}`);
+    return;
+  }
+
+  if (!res || !res.ok) {
+    deny(`bridge error: ${res?.error || 'unknown'}`);
+    return;
+  }
+
+  // Bridge signals one of: 'not-gated' | 'approved' | 'denied' | 'timeout' | 'auto-approved'
+  if (res.decision === 'not-gated' || res.decision === 'approved' || res.decision === 'auto-approved') {
+    // Pass through — let the default permission flow decide. An empty
+    // stdout + exit 0 means "no opinion" from this hook.
+    process.exit(0);
+  }
+
+  const reason = res.reason || `approval ${res.decision}`;
+  deny(reason, res.decision);
+})().catch((err) => {
+  deny(`hook crashed: ${err.message}`);
+});
+
+function deny(reason, decision = 'denied') {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: `[${decision}] ${reason}`,
+    },
+  };
+  try {
+    process.stdout.write(JSON.stringify(out));
+  } catch {}
+  process.exit(2);
+}