polygram 0.1.0

package/lib/voice.js

@@ -0,0 +1,146 @@
+/**
+ * Voice-to-code transcription.
+ *
+ * `transcribe(filePath, opts)` turns a voice/audio file into text. Two
+ * backends:
+ *   - openai: POST the file to api.openai.com/v1/audio/transcriptions
+ *   - local:  shell out to whisper.cpp (`-otxt`) and read the .txt sibling
+ *
+ * The backend is injected so tests can stub it without touching the network.
+ * Returns `{ text, language, duration_sec, cost_usd, provider }`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const OPENAI_COST_PER_MINUTE_USD = 0.006;
+
+function isVoiceAttachment(att) {
+  if (!att) return false;
+  if (att.kind === 'voice') return true;
+  if (att.kind === 'audio') return true;
+  return false;
+}
+
+function isLikelyAudioMime(mime) {
+  return typeof mime === 'string' && mime.startsWith('audio/');
+}
+
+/**
+ * Normalize language hint. "auto" is dropped (let Whisper auto-detect).
+ */
+function normaliseLanguage(lang) {
+  if (!lang || lang === 'auto') return null;
+  return String(lang).slice(0, 5).toLowerCase();
+}
+
+async function transcribeOpenAI(filePath, opts) {
+  const apiKey = process.env[opts.apiKeyEnv || 'OPENAI_API_KEY'];
+  if (!apiKey) throw new Error(`OPENAI_API_KEY env not set (or ${opts.apiKeyEnv})`);
+
+  // Node 18+ has native FormData + fetch. Keep it dep-free.
+  const form = new FormData();
+  const buf = fs.readFileSync(filePath);
+  form.append('file', new Blob([buf]), path.basename(filePath));
+  form.append('model', opts.model || 'whisper-1');
+  form.append('response_format', 'verbose_json');
+  const lang = normaliseLanguage(opts.language);
+  if (lang) form.append('language', lang);
+
+  const res = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: form,
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`whisper openai ${res.status}: ${body.slice(0, 200)}`);
+  }
+  const j = await res.json();
+  const duration_sec = typeof j.duration === 'number' ? j.duration : 0;
+  return {
+    text: (j.text || '').trim(),
+    language: j.language || null,
+    duration_sec,
+    cost_usd: (duration_sec / 60) * OPENAI_COST_PER_MINUTE_USD,
+    provider: 'openai',
+  };
+}
+
+async function transcribeLocal(filePath, opts) {
+  const binary = opts.binary;
+  const model = opts.model;
+  if (!binary || !fs.existsSync(binary)) {
+    throw new Error(`whisper.cpp binary not found: ${binary}`);
+  }
+  if (!model || !fs.existsSync(model)) {
+    throw new Error(`whisper.cpp model not found: ${model}`);
+  }
+
+  // whisper.cpp writes <input>.txt alongside the input with -otxt.
+  const args = ['-m', model, '-f', filePath, '-otxt', '-nt'];
+  const lang = normaliseLanguage(opts.language);
+  if (lang) args.push('-l', lang);
+
+  return await new Promise((resolve, reject) => {
+    let stderr = '';
+    const p = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    p.stderr.on('data', (d) => { stderr += d.toString(); });
+    p.once('error', reject);
+    p.once('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`whisper.cpp exit ${code}: ${stderr.slice(0, 200)}`));
+        return;
+      }
+      const txtPath = `${filePath}.txt`;
+      let text = '';
+      try { text = fs.readFileSync(txtPath, 'utf8').trim(); } catch {}
+      // Derive duration from stderr (whisper.cpp prints total duration).
+      const dMatch = stderr.match(/total duration\s*=\s*([\d.]+)/i);
+      const duration_sec = dMatch ? parseFloat(dMatch[1]) : 0;
+      const lMatch = stderr.match(/detected language:\s*(\w+)/i);
+      resolve({
+        text,
+        language: lMatch ? lMatch[1] : null,
+        duration_sec,
+        cost_usd: 0,
+        provider: 'local',
+      });
+    });
+  });
+}
+
+/**
+ * Main entrypoint. `opts.provider` picks the backend ('openai' | 'local').
+ * `opts.fetchFn` / `opts.spawnFn` allow test injection.
+ */
+async function transcribe(filePath, opts = {}) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    throw new Error(`file missing: ${filePath}`);
+  }
+  const stat = fs.statSync(filePath);
+  if (!stat.size) throw new Error(`file empty: ${filePath}`);
+  if (opts.maxDurationSec && opts.maxDurationBytesPerSec) {
+    const estSec = stat.size / opts.maxDurationBytesPerSec;
+    if (estSec > opts.maxDurationSec) {
+      throw new Error(
+        `file likely exceeds max duration (${estSec.toFixed(0)}s > ${opts.maxDurationSec}s)`,
+      );
+    }
+  }
+  const provider = opts.provider || 'openai';
+  if (provider === 'openai') return transcribeOpenAI(filePath, opts);
+  if (provider === 'local') return transcribeLocal(filePath, opts);
+  throw new Error(`unknown voice provider: ${provider}`);
+}
+
+module.exports = {
+  transcribe,
+  transcribeOpenAI,
+  transcribeLocal,
+  isVoiceAttachment,
+  isLikelyAudioMime,
+  normaliseLanguage,
+  OPENAI_COST_PER_MINUTE_USD,
+};

package/migrations/001-initial.sql

@@ -0,0 +1,93 @@
+-- Telegram Bridge v2 — initial schema
+-- Run once. Subsequent schema changes use additional migration files.
+
+CREATE TABLE IF NOT EXISTS sessions (
+  session_key TEXT PRIMARY KEY,
+  chat_id TEXT NOT NULL,
+  thread_id TEXT,
+  claude_session_id TEXT NOT NULL,
+  agent TEXT,
+  cwd TEXT,
+  model TEXT,
+  effort TEXT,
+  created_ts INTEGER NOT NULL,
+  last_active_ts INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS chat_migrations (
+  old_chat_id TEXT PRIMARY KEY,
+  new_chat_id TEXT NOT NULL,
+  migrated_ts INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  chat_id TEXT NOT NULL,
+  thread_id TEXT,
+  msg_id INTEGER NOT NULL,
+  user TEXT,
+  user_id INTEGER,
+  text TEXT,
+  reply_to_id INTEGER,
+  direction TEXT CHECK(direction IN ('in','out','system')),
+  source TEXT,
+  bot_name TEXT,
+  attachments_json TEXT,
+  session_id TEXT,
+  model TEXT,
+  effort TEXT,
+  turn_id TEXT,
+  status TEXT CHECK(status IN ('pending','sent','failed','received')) DEFAULT 'received',
+  error TEXT,
+  cost_usd REAL,
+  ts INTEGER NOT NULL,
+  edited_ts INTEGER,
+  UNIQUE(chat_id, msg_id)
+);
+CREATE INDEX IF NOT EXISTS idx_recent ON messages(chat_id, thread_id, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_reply ON messages(chat_id, reply_to_id);
+CREATE INDEX IF NOT EXISTS idx_turn ON messages(turn_id) WHERE turn_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_pending ON messages(status, ts) WHERE status = 'pending';
+
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+  text, user,
+  content=messages, content_rowid=id,
+  tokenize='unicode61 remove_diacritics 2'
+);
+
+-- External-content FTS5: use 'delete' command so the old tokens are purged.
+-- Plain DELETE/UPDATE on messages_fts leaves orphans.
+CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+  INSERT INTO messages_fts(rowid, text, user) VALUES (new.id, new.text, new.user);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN
+  INSERT INTO messages_fts(messages_fts, rowid, text, user) VALUES ('delete', old.id, old.text, old.user);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_au AFTER UPDATE ON messages BEGIN
+  INSERT INTO messages_fts(messages_fts, rowid, text, user) VALUES ('delete', old.id, old.text, old.user);
+  INSERT INTO messages_fts(rowid, text, user) VALUES (new.id, new.text, new.user);
+END;
+
+CREATE TABLE IF NOT EXISTS config_changes (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  chat_id TEXT NOT NULL,
+  thread_id TEXT,
+  field TEXT NOT NULL CHECK(field IN ('model','effort','agent')),
+  old_value TEXT,
+  new_value TEXT NOT NULL,
+  user_id INTEGER,
+  user TEXT,
+  source TEXT,
+  ts INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_config_recent ON config_changes(chat_id, ts DESC);
+
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  chat_id TEXT,
+  kind TEXT NOT NULL,
+  detail_json TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_events_recent ON events(ts DESC);
+CREATE INDEX IF NOT EXISTS idx_events_kind ON events(kind, ts DESC);

package/migrations/002-fix-fts-triggers.sql

@@ -0,0 +1,24 @@
+-- Fix FTS5 triggers for external-content tables.
+-- The v1 triggers used plain UPDATE/DELETE on messages_fts which doesn't purge
+-- old tokens from the index. Switch to the documented 'delete' command form
+-- and rebuild the FTS index so any orphan tokens from pre-fix writes are gone.
+
+DROP TRIGGER IF EXISTS messages_ai;
+DROP TRIGGER IF EXISTS messages_au;
+DROP TRIGGER IF EXISTS messages_ad;
+
+CREATE TRIGGER messages_ai AFTER INSERT ON messages BEGIN
+  INSERT INTO messages_fts(rowid, text, user) VALUES (new.id, new.text, new.user);
+END;
+
+CREATE TRIGGER messages_ad AFTER DELETE ON messages BEGIN
+  INSERT INTO messages_fts(messages_fts, rowid, text, user) VALUES ('delete', old.id, old.text, old.user);
+END;
+
+CREATE TRIGGER messages_au AFTER UPDATE ON messages BEGIN
+  INSERT INTO messages_fts(messages_fts, rowid, text, user) VALUES ('delete', old.id, old.text, old.user);
+  INSERT INTO messages_fts(rowid, text, user) VALUES (new.id, new.text, new.user);
+END;
+
+-- Rebuild index from scratch to discard any stale tokens.
+INSERT INTO messages_fts(messages_fts) VALUES ('rebuild');

package/migrations/003-pairings.sql

@@ -0,0 +1,33 @@
+-- Feature 1: pairing codes for live onboarding without bridge restarts.
+
+-- Pairing codes (single-use, short-lived).
+CREATE TABLE pair_codes (
+  code              TEXT PRIMARY KEY,
+  bot_name          TEXT NOT NULL,
+  chat_id           TEXT,                  -- NULL = valid in any of the bot's chats
+  scope             TEXT NOT NULL CHECK(scope IN ('user','chat')),
+  issued_by_user_id INTEGER NOT NULL,
+  issued_ts         INTEGER NOT NULL,
+  expires_ts        INTEGER NOT NULL,
+  used_by_user_id   INTEGER,
+  used_ts           INTEGER,
+  note              TEXT
+);
+CREATE INDEX idx_pair_codes_expiry ON pair_codes(expires_ts) WHERE used_ts IS NULL;
+CREATE INDEX idx_pair_codes_bot    ON pair_codes(bot_name, issued_ts);
+
+-- Active pairings: the result of a successful /pair <CODE>.
+-- Soft-deleted via revoked_ts for audit trail.
+CREATE TABLE pairings (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  bot_name            TEXT NOT NULL,
+  user_id             INTEGER NOT NULL,
+  chat_id             TEXT,                -- NULL = valid in any of the bot's chats
+  granted_ts          INTEGER NOT NULL,
+  granted_by_user_id  INTEGER NOT NULL,
+  revoked_ts          INTEGER,
+  note                TEXT,
+  UNIQUE(bot_name, user_id, chat_id)
+);
+CREATE INDEX idx_pairings_lookup ON pairings(bot_name, user_id)
+  WHERE revoked_ts IS NULL;

package/migrations/004-approvals.sql

@@ -0,0 +1,28 @@
+-- Feature 2: inline keyboard approvals for destructive tools.
+
+CREATE TABLE pending_approvals (
+  id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+  bot_name             TEXT NOT NULL,
+  turn_id              TEXT,              -- joins back to messages.turn_id (nullable: hook might not know)
+  requester_chat_id    TEXT NOT NULL,     -- chat whose Claude is asking
+  approver_chat_id     TEXT NOT NULL,     -- chat where the keyboard landed
+  approver_msg_id      INTEGER,           -- Telegram msg_id of the keyboard (set after send)
+  tool_name            TEXT NOT NULL,     -- "Bash", "mcp__shopify__order_cancel"
+  tool_input_json      TEXT NOT NULL,
+  tool_input_digest    TEXT NOT NULL,     -- sha256 prefix; dedups repeated hook fires
+  callback_token       TEXT NOT NULL,     -- random token in callback_data to defeat replay
+  status               TEXT NOT NULL
+    CHECK(status IN ('pending','approved','denied','timeout','cancelled'))
+    DEFAULT 'pending',
+  requested_ts         INTEGER NOT NULL,
+  decided_ts           INTEGER,
+  decided_by_user_id   INTEGER,
+  decided_by_user      TEXT,
+  timeout_ts           INTEGER NOT NULL,
+  reason               TEXT               -- operator-supplied deny reason (future)
+);
+CREATE INDEX idx_approvals_pending ON pending_approvals(status, timeout_ts)
+  WHERE status = 'pending';
+CREATE INDEX idx_approvals_turn    ON pending_approvals(turn_id);
+CREATE INDEX idx_approvals_dedup   ON pending_approvals(bot_name, turn_id, tool_input_digest)
+  WHERE status = 'pending';

package/ops/README.md

@@ -0,0 +1,110 @@
+# ops/ — launchd plists for per-bot process isolation
+
+Each bot runs in its own Node process. `--bot <name>` is required on every
+invocation — the bridge refuses to boot without it. These user-scope
+LaunchAgents supervise them individually so a crash in one bot never takes
+down another.
+
+## Install
+
+```bash
+mkdir -p /Users/$USER/polygram/logs
+# For each bot, render the template to LaunchAgents with the bot's name
+# and your username substituted in:
+cp ops/polygram.plist.example ~/Library/LaunchAgents/com.polygram.my-bot.plist
+sed -i '' "s/BOTNAME/my-bot/g; s|YOURNAME|$USER|g" \
+  ~/Library/LaunchAgents/com.polygram.my-bot.plist
+launchctl load ~/Library/LaunchAgents/com.polygram.my-bot.plist
+```
+
+Repeat for each bot.
+
+## Manage
+
+```bash
+# Status of all
+launchctl list | grep polygram
+
+# Restart one
+launchctl kickstart -k gui/$(id -u)/com.polygram.my-bot
+
+# Stop / start
+launchctl unload ~/Library/LaunchAgents/com.polygram.my-bot.plist
+launchctl load   ~/Library/LaunchAgents/com.polygram.my-bot.plist
+
+# Tail logs
+tail -f /Users/$USER/polygram/logs/my-bot.log
+```
+
+## Adding a new bot
+
+1. Render a new plist from `polygram.plist.example` (see Install).
+2. Add `bots.<new>` and any `chats` entries in `config.json`.
+3. `launchctl load ~/Library/LaunchAgents/com.polygram.<new>.plist`.
+
+Existing bots keep running — no shared process, no restart.
+
+## Design choice: user-level LaunchAgents, not LaunchDaemons
+
+- LaunchAgents live in `~/Library/LaunchAgents/`, run as the logged-in user,
+  no sudo required.
+- LaunchDaemons (`/Library/LaunchDaemons/`) would run as root at boot — nice
+  for headless servers, overkill for a per-user Mac install. LaunchAgents
+  fire at login and stay running.
+
+## Local development
+
+For running outside launchd:
+
+```bash
+cd /Users/$USER/polygram
+node bridge.js --bot admin-bot     # in one tmux window
+node bridge.js --bot partner-bot   # in another
+```
+
+Each is independent. Kill one, the other keeps serving. There is no
+"run all bots in one process" mode — `--bot` is required.
+
+`--db <path>` overrides the default DB location (`<repo>/<bot>.db`).
+Useful for dry-running new bots against a throwaway DB without touching
+production files.
+
+## One-time: split shared bridge.db into per-bot DBs
+
+If you migrated from an earlier build that used a single shared `bridge.db`:
+
+```bash
+cd /Users/$USER/polygram
+
+# Dry run first
+node scripts/split-db.js --config config.json --dry-run
+
+# For real (archives bridge.db to bridge.db.archived-<stamp>)
+launchctl unload ~/Library/LaunchAgents/com.polygram.*.plist
+node scripts/split-db.js --config config.json
+launchctl load   ~/Library/LaunchAgents/com.polygram.my-bot.plist
+# ... repeat load for each bot
+```
+
+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 jobs that want to post to Telegram must address a specific bot:
+
+```js
+const { tell } = require('polygram/lib/ipc-client');
+
+await tell('admin-bot', 'sendMessage', {
+  chat_id: '111111111',
+  text: 'Billing synced.',
+}, { source: 'cron:billing-sync' });
+```
+
+Allowed methods: `sendMessage`, `sendPhoto`, `sendDocument`, `sendSticker`,
+`sendChatAction`, `editMessageText`, `setMessageReaction`. Other methods
+are rejected server-side.
+
+If the target bot is down, `tell()` throws. Intentional — cron failures
+should surface, not silently log to a DB the bot isn't watching.

package/ops/polygram.plist.example

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Template: one plist per bot. Replace BOTNAME and YOURNAME.
+
+  Install:
+    cp ops/polygram.plist.example ~/Library/LaunchAgents/com.polygram.BOTNAME.plist
+    sed -i '' 's/BOTNAME/my-admin-bot/g; s|YOURNAME|'"$USER"'|g' \
+      ~/Library/LaunchAgents/com.polygram.BOTNAME.plist
+    launchctl load ~/Library/LaunchAgents/com.polygram.BOTNAME.plist
+
+  Restart:
+    launchctl kickstart -k gui/$(id -u)/com.polygram.BOTNAME
+
+  Logs:
+    tail -f /Users/YOURNAME/polygram/logs/BOTNAME.log
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.polygram.BOTNAME</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/node</string>
+        <string>/Users/YOURNAME/polygram/bridge.js</string>
+        <string>--bot</string>
+        <string>BOTNAME</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/YOURNAME/polygram</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>StandardOutPath</key>
+    <string>/Users/YOURNAME/polygram/logs/BOTNAME.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/YOURNAME/polygram/logs/BOTNAME.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/Users/YOURNAME/.npm-global/bin</string>
+        <key>HOME</key>
+        <string>/Users/YOURNAME</string>
+        <key>NODE_ENV</key>
+        <string>production</string>
+    </dict>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+</dict>
+</plist>

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "polygram",
+  "version": "0.1.0",
+  "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": {
+    "polygram": "bridge.js",
+    "polygram-split-db": "scripts/split-db.js"
+  },
+  "files": [
+    "bridge.js",
+    "bin/",
+    "lib/",
+    "migrations/",
+    "scripts/split-db.js",
+    "scripts/ipc-smoke.js",
+    "skills/",
+    "ops/polygram.plist.example",
+    "ops/README.md",
+    "config.example.json"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "start": "node bridge.js",
+    "split-db": "node scripts/split-db.js",
+    "ipc-smoke": "node scripts/ipc-smoke.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "claude-code",
+    "bot",
+    "daemon",
+    "multi-bot",
+    "sqlite",
+    "transcript"
+  ],
+  "author": "Ivan Shumkov <ivan.shumkov@dash.org>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shumkov/polygram.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shumkov/polygram/issues"
+  },
+  "homepage": "https://github.com/shumkov/polygram#readme",
+  "type": "commonjs",
+  "dependencies": {
+    "better-sqlite3": "^12.9.0",
+    "grammy": "^1.42.0"
+  }
+}

package/scripts/ipc-smoke.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Quick IPC round-trip probe.
+ * Usage: node scripts/ipc-smoke.js <bot-name>
+ */
+
+const { call, socketPathFor } = require('../lib/ipc-client');
+
+(async () => {
+  const bot = process.argv[2] || 'shumabit';
+  const path = socketPathFor(bot);
+
+  console.log('path:', path);
+  console.log('ping:', JSON.stringify(await call({ path, op: 'ping' })));
+
+  console.log('ungated:', JSON.stringify(await call({
+    path, op: 'approval_request',
+    payload: {
+      bot_name: bot, chat_id: '111111111',
+      tool_name: 'Read', tool_input: { path: '/etc/hosts' },
+    },
+  })));
+
+  console.log('DONE');
+})().catch((err) => {
+  console.error('ERR:', err.message);
+  process.exit(1);
+});