polygram 0.2.0 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "shumkov",
+  "description": "Ivan Shumkov's Claude Code plugins.",
+  "owner": {
+    "name": "Ivan Shumkov",
+    "email": "ivanshumkov@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "polygram",
+      "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Bundles /polygram:status|logs|pair-code|approvals admin commands and a history skill.",
+      "category": "integration",
+      "source": "./",
+      "homepage": "https://github.com/shumkov/polygram"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands and a history skill.",
   "keywords": [
     "telegram",

package/README.md

@@ -87,23 +87,31 @@ Practical differences that matter for migration:
 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
+# Global binary:
+npm install -g polygram
+
+# Data directory (config + per-bot DBs + inbox live here):
+mkdir ~/polygram && cd ~/polygram
+cp $(npm root -g)/polygram/config.example.json config.json
+# edit config.json: bot tokens from @BotFather, chat IDs, cwds
 ```
 
 ## Run
 
 ```bash
-node polygram.js --bot admin-bot          # one bot, one process
-node polygram.js --bot partner-bot        # another bot, another process
+cd ~/polygram
+polygram --bot admin-bot          # one bot, one process
+polygram --bot partner-bot        # another bot, another process
 ```
 
-`--bot` is required. Each process creates `<bot>.db` next to `polygram.js`
-on first run (migrations apply automatically) and opens a Unix socket at
-`/tmp/polygram-<bot>.sock`.
+`--bot` is required. Paths resolve from your current working directory:
+
+- `config.json` → `$PWD/config.json` (override with `--config` or `POLYGRAM_CONFIG`)
+- `<bot>.db` → `$PWD/<bot>.db` (override with `--db` or `POLYGRAM_DB`)
+- `inbox/` → `$PWD/inbox/` (override with `POLYGRAM_INBOX`)
+
+Migrations are bundled in the package and apply automatically. The daemon
+opens a Unix socket at `/tmp/polygram-<bot>.sock`.
 
 For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
 
@@ -112,23 +120,40 @@ For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
 polygram also ships as a Claude Code plugin — adds admin slash commands
 and bundles the transcript-query skill for use inside your Claude sessions.
 
+The repo doubles as a single-plugin marketplace. Two commands at your
+Claude Code `/` prompt:
+
+```
+/plugin marketplace add https://github.com/shumkov/polygram.git
+/plugin install polygram@shumkov
 ```
-/plugin install https://github.com/shumkov/polygram.git
+
+The first registers the marketplace (`shumkov`). The second installs the
+`polygram` plugin from it.
+
+To enable in a specific Claude project, add to `.claude/settings.json`:
+
+```json
+{
+  "enabledPlugins": {
+    "polygram@shumkov": true
+  }
+}
 ```
 
-Once installed:
+Once enabled:
 
-- `/polygram:status` — running bots, IPC health, recent events, one-line verdict
+- `/polygram:status` — running bots, IPC health, recent events
 - `/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:
+The bundled **`history` skill** lets Claude query the transcript directly
+when you ask about past chat activity:
 
 ```
 "Summarise the Orders topic today" →
-  uses skills/history to run `recent <chat> --since 24h`
+  Claude invokes the history skill → runs `recent <chat> --since 24h`
 ```
 
 Scope is derived from `process.cwd()`: the skill refuses to run from an

package/commands/status.md

@@ -21,9 +21,9 @@ a short Markdown table (one row per bot):
    ```
    Interpret the result:
    - `ping: {"id":null,"ok":true,"pong":true,"bot":"<bot>"}` → socket alive
-   - `ERR: connect ECONNREFUSED` → socket stale (bridge not actually
+   - `ERR: connect ECONNREFUSED` → socket stale (polygram not actually
      serving despite plist being loaded)
-   - `ERR: ENOENT` → socket missing (bridge never got that far at boot)
+   - `ERR: ENOENT` → socket missing (polygram never got that far at boot)
 
 3. **Recent events in each bot's DB.** For every bot, run:
    ```

package/lib/attachments.js

@@ -38,7 +38,7 @@ function filterAttachments(attachments, opts = {}) {
     const size = a.size || 0;
     // Telegram sometimes reports file_size=0 or omits it. Those bypass the
     // cap here but the download step MUST re-check Content-Length and actual
-    // bytes — see downloadAttachments in bridge.js.
+    // bytes — see downloadAttachments in polygram.js.
     if (size > maxFileBytes) {
       rejected.push({ att: a, reason: `exceeds per-file cap (${maxFileBytes} bytes, got ${size})` });
       continue;

package/lib/db.js

@@ -172,7 +172,7 @@ function wrap(db) {
         text: row.text || '',
         reply_to_id: row.reply_to_id || null,
         direction: row.direction || 'in',
-        source: row.source || 'bridge',
+        source: row.source || 'polygram',
         bot_name: row.bot_name || null,
         attachments_json: row.attachments_json || null,
         session_id: row.session_id || null,
@@ -192,7 +192,7 @@ function wrap(db) {
         thread_id: row.thread_id ? String(row.thread_id) : null,
         user: row.user || null,
         text: row.text || '',
-        source: row.source || 'bridge',
+        source: row.source || 'polygram',
         bot_name: row.bot_name || null,
         turn_id: row.turn_id || null,
         session_id: row.session_id || null,

package/lib/inbox.js

@@ -2,8 +2,8 @@
  * Inbox on-disk helpers.
  *
  * `sweepInbox(dir, maxAgeMs)` deletes files under each chat subdir whose
- * mtime is older than `maxAgeMs`. Called on bridge boot so a long-running
- * bridge doesn't accumulate every file a user has ever sent.
+ * mtime is older than `maxAgeMs`. Called on polygram boot so a long-running
+ * polygram doesn't accumulate every file a user has ever sent.
  */
 
 const fs = require('fs');

package/lib/queue-utils.js

@@ -1,6 +1,6 @@
 /**
- * Pure helpers for per-chat message queues. Kept separate from bridge.js so
- * they can be unit-tested without spinning up the whole bridge.
+ * Pure helpers for per-chat message queues. Kept separate from polygram.js so
+ * they can be unit-tested without spinning up the whole polygram.
  */
 
 // Drop queued items belonging to a chatId across all its thread-scoped

package/migrations/003-pairings.sql

@@ -1,4 +1,4 @@
--- Feature 1: pairing codes for live onboarding without bridge restarts.
+-- Feature 1: pairing codes for live onboarding without polygram restarts.
 
 -- Pairing codes (single-use, short-lived).
 CREATE TABLE pair_codes (

package/ops/README.md

@@ -89,7 +89,7 @@ launchctl load   ~/Library/LaunchAgents/com.polygram.my-bot.plist
 The script is idempotent; safe to re-run. It refuses to proceed if a WAL
 file on the source DB indicates a live writer.
 
-## Cron → bridge (IPC, not direct DB write)
+## Cron → polygram (IPC, not direct DB write)
 
 Cron jobs that want to post to Telegram must address a specific bot:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.2.0",
+  "version": "0.3.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": {

package/polygram.js

@@ -6,7 +6,7 @@
  * Process stays warm: no cold start, full prompt caching.
  *
  * Architecture:
- *   Telegram (grammy long-poll) → bridge receives message
+ *   Telegram (grammy long-poll) → polygram receives message
  *   → looks up per-chat config (model, effort, agent, cwd)
  *   → sends to persistent claude process via stdin (stream-json)
  *   → reads response from stdout (stream-json)
@@ -41,17 +41,21 @@ const {
 const ipcServer = require('./lib/ipc-server');
 
 // ─── Config ──────────────────────────────────────────────────────────
-
-const CONFIG_PATH = path.join(__dirname, 'config.json');
-const SESSIONS_JSON_PATH = path.join(__dirname, 'sessions.json'); // legacy, imported once on boot
-const DB_DIR = __dirname;
+//
+// User data (config, per-bot DBs, inbox) resolves from the cwd the operator
+// runs polygram in. Package resources (migrations/) stay under __dirname.
+// This makes `npm install -g polygram` + `cd ~/my-data && polygram --bot X`
+// work without symlinks or POLYGRAM_DIR gymnastics.
+
+const DATA_DIR = process.cwd();
+const CONFIG_PATH = process.env.POLYGRAM_CONFIG || path.join(DATA_DIR, 'config.json');
+const SESSIONS_JSON_PATH = path.join(DATA_DIR, 'sessions.json'); // legacy, imported once on boot
+const DB_DIR = DATA_DIR;
 // DB_PATH is resolved in main() from --db or <bot>.db default.
 let DB_PATH = null;
-// Paths that vary per deployment are env-configurable. Defaults preserve
-// the author's local layout for back-compat but the repo itself is portable.
 const STICKERS_PATH = process.env.POLYGRAM_STICKERS
-  || path.join(process.env.HOME || '', 'polygram-stickers.json');
-const INBOX_DIR = process.env.POLYGRAM_INBOX || path.join(__dirname, 'inbox');
+  || path.join(DATA_DIR, 'stickers.json');
+const INBOX_DIR = process.env.POLYGRAM_INBOX || path.join(DATA_DIR, 'inbox');
 const CLAUDE_BIN = process.env.POLYGRAM_CLAUDE_BIN
   || path.join(process.env.HOME || '', '.npm-global/bin/claude');
 const CHILD_HOME = process.env.POLYGRAM_CHILD_HOME || process.env.HOME || '';
@@ -181,7 +185,7 @@ function recordInbound(msg) {
     text: msg.text || msg.caption || '',
     reply_to_id: msg.reply_to_message?.message_id || null,
     direction: 'in',
-    source: 'bridge',
+    source: 'polygram',
     bot_name: BOT_NAME,
     attachments_json: attachments.length ? JSON.stringify(attachments) : null,
     model: chatConfig?.model || null,
@@ -1507,7 +1511,7 @@ async function main() {
       console.log(`[inbox] swept ${swept.swept} files (${(swept.bytes / 1_048_576).toFixed(1)} MiB) older than ${inboxRetentionMs / 86_400_000}d`);
       db.logEvent('inbox-swept', { files: swept.swept, bytes: swept.bytes, retention_days: inboxRetentionMs / 86_400_000 });
     }
-    db.logEvent('bridge-start', { migration: migration.reason, imported: migration.imported });
+    db.logEvent('polygram-start', { migration: migration.reason, imported: migration.imported });
   } catch (err) {
     console.error(`[db] FATAL: ${err.message}`);
     console.error('Bridge cannot run without a DB (Phase 2: DB is source of truth).');
@@ -1555,12 +1559,12 @@ async function main() {
     try { fs.unlinkSync(ipcServer.secretPathFor(BOT_NAME)); } catch {}
     // Resolve any blocked hook waiters so Claude processes don't hang.
     for (const list of approvalWaiters.values()) {
-      for (const fn of list) { try { fn('cancelled', 'bridge shutting down'); } catch {} }
+      for (const fn of list) { try { fn('cancelled', 'polygram shutting down'); } catch {} }
     }
     approvalWaiters.clear();
     if (pm) pm.shutdown().catch(() => {});
     if (db) {
-      try { db.logEvent('bridge-stop'); db.raw.close(); } catch {}
+      try { db.logEvent('polygram-stop'); db.raw.close(); } catch {}
     }
     setTimeout(() => process.exit(0), 1000);
   };

package/scripts/split-db.js

@@ -59,7 +59,7 @@ function main() {
   console.log(`[split-db] bots: ${bots.join(', ')}`);
   if (dryRun) console.log('[split-db] DRY RUN - no files written or renamed');
 
-  // Refuse to split if a live bridge is writing to srcPath. The WAL file's
+  // Refuse to split if a live polygram is writing to srcPath. The WAL file's
   // presence + recent mtime is a strong proxy: SQLite WAL checkpoints after
   // ~1000 pages or a clean close, so a hot WAL means an active writer.
   refuseIfActiveWriter(srcPath);
@@ -87,7 +87,7 @@ function main() {
     }
   });
   // `transaction` runs deferred by default; we want immediate write-lock
-  // on the source to block any concurrent bridge from slipping in.
+  // on the source to block any concurrent polygram from slipping in.
   srcTx.immediate();
 
   src.raw.close();
@@ -112,7 +112,7 @@ function refuseIfActiveWriter(srcPath) {
   const wal = `${srcPath}-wal`;
   if (!fs.existsSync(wal)) return;
   const age = Date.now() - fs.statSync(wal).mtimeMs;
-  // 60s is generous — a clean bridge shutdown checkpoints the WAL.
+  // 60s is generous — a clean polygram shutdown checkpoints the WAL.
   // A hot WAL (< 60s) strongly suggests a live writer.
   if (age < 60_000) {
     console.error(`[split-db] refusing: ${wal} is active (mtime ${Math.round(age/1000)}s ago)`);

package/skills/history/SKILL.md

@@ -52,6 +52,6 @@ Flags: `--days 7`
 
 # Notes
 
-- DB opened read-only — safe to run alongside the live bridge.
+- DB opened read-only — safe to run alongside the live polygram.
 - Output capped at 500 rows. Narrow with `--since` or `--days` for wide queries.
 - Times in `ts` are ms epoch. `formatPretty` shows local HH:MM.

package/skills/history/scripts/query.js

@@ -106,7 +106,7 @@ function deriveBotScope(cfg) {
 }
 
 function openDbReadOnly(dbPath) {
-  if (!fs.existsSync(dbPath)) die(`bridge DB not found at ${dbPath}`);
+  if (!fs.existsSync(dbPath)) die(`polygram DB not found at ${dbPath}`);
   const raw = new Database(dbPath, { readonly: true, fileMustExist: true });
   return { raw };
 }