polygram 0.8.0-rc.56 → 0.8.0-rc.58

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "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.",
+      "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 plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
       "category": "integration",
       "source": "./",
       "homepage": "https://github.com/shumkov/polygram"

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.8.0-rc.56",
-  "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.",
+  "version": "0.8.0-rc.58",
+  "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 plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",
     "openclaw",

package/lib/ipc-file-validator.js

@@ -0,0 +1,75 @@
+/**
+ * rc.58: validate the `document`/`photo`/etc file param on IPC sends
+ * before relaying to Telegram, so agents get a clear error instead
+ * of Telegram's cryptic "Wrong port number specified" rejection.
+ *
+ * Discovery: 2026-05-05 — agent generated an Artisan invoice .docx,
+ * tried to deliver via polygram-ipc with `document: 'http://...'`
+ * pointing at a localhost HTTP server it spun up. Telegram rejected
+ * because (1) it can't reach the agent's Mac, (2) port format was
+ * malformed. The rejection error read "Wrong port number specified"
+ * which gave neither agent nor operator a useful clue.
+ *
+ * What's accepted:
+ *   - { source: '/abs/path' } envelope — preferred for local files
+ *   - public HTTPS URL — Telegram fetches it
+ *   - Telegram file_id — short alphanumeric string, no scheme/slashes
+ *
+ * What's rejected at the IPC layer (clear error returned to caller):
+ *   - localhost / 127.0.0.1 URLs (Telegram can't reach)
+ *   - http:// URLs (Telegram requires https)
+ *   - bare absolute paths (must wrap in { source: ... })
+ *   - non-https schemes
+ *
+ * What's PASSED THROUGH (caller's responsibility):
+ *   - { source: '/abs/path' } — grammy handles multipart upload
+ *   - https URL string — Telegram validates reachability itself
+ *   - file_id-shaped string — Telegram resolves
+ *   - Buffer / Stream / other grammy InputFile shapes
+ */
+
+'use strict';
+
+const FILE_PARAM_BY_METHOD = {
+  sendDocument: 'document',
+  sendPhoto: 'photo',
+  sendAudio: 'audio',
+  sendAnimation: 'animation',
+  sendVideo: 'video',
+  sendVoice: 'voice',
+};
+
+/**
+ * @param {string} method - IPC method name (e.g. 'sendDocument')
+ * @param {object} params - the params payload
+ * @returns {string|null} human-readable error if the file param is
+ *   malformed, null if the params look fine (or the method has no
+ *   file param to check).
+ */
+function validateIpcFileParam(method, params = {}) {
+  const fileParam = FILE_PARAM_BY_METHOD[method];
+  if (!fileParam) return null;
+  const val = params[fileParam];
+  if (typeof val !== 'string') return null;       // envelope/Buffer/etc — pass through
+  if (val.length === 0) return `polygram IPC: ${fileParam} is empty`;
+
+  const looksUrl = /^(https?|ftp):\/\//i.test(val);
+  const isLocalhost = /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1?\])(\b|[:/?#])/i.test(val);
+  const isAbsPath = val.startsWith('/');
+
+  if (isLocalhost) {
+    return `polygram IPC: localhost URLs unreachable from Telegram (got: ${val.slice(0, 80)}). Use { source: '/abs/path' } for local files, or a publicly reachable HTTPS URL.`;
+  }
+  if (looksUrl && !/^https:\/\//i.test(val)) {
+    return `polygram IPC: only HTTPS URLs supported for ${fileParam} (got: ${val.slice(0, 80)}). Use https://, { source: '/abs/path' } for local files, or a Telegram file_id.`;
+  }
+  if (isAbsPath && !looksUrl) {
+    return `polygram IPC: bare file path not accepted (got: ${val.slice(0, 80)}). Wrap it: { ${fileParam}: { source: '${val}' } } so grammy uploads as multipart.`;
+  }
+  return null;
+}
+
+module.exports = {
+  validateIpcFileParam,
+  FILE_PARAM_BY_METHOD,
+};

package/lib/process-manager-sdk.js

@@ -648,11 +648,58 @@ class ProcessManagerSdk {
 
       let idleTimer = null;
       let maxTimer = null;
+      let visibilityTimer = null;
       let activated = false;
 
+      // rc.58: visibility heartbeat for long silent tool runs.
+      //
+      // The SDK can stay silent for minutes when the agent is running
+      // a single long Bash/Playwright tool (gcloud auth + Chrome
+      // OAuth login dance, multi-step Playwright session, etc.).
+      // During the silence:
+      //   - polygram receives no onChunk, no onToolUse, no onResult
+      //   - reactor's stall (30s) and freeze (180s) timers fire IF
+      //     the reactor was in a STALL_PROMOTABLE state at last
+      //     heartbeat — but if it was just stopped or in AUTOSTEERED
+      //     terminal state, no visible signal fires
+      //   - user sees "stuck" with no emoji/typing change for minutes
+      //
+      // This timer pings the head pending's reactor every 30s while
+      // the pending is in flight. It does NOT change the reactor's
+      // visible state (heartbeat is idempotent — re-arms timers
+      // without flushing) — but it ensures the stall/freeze cycle
+      // keeps producing visible promotions even if SDK silence
+      // would otherwise let the reactor go fully quiet.
+      //
+      // Discovery: 2026-05-05 09:58:38 → 10:10:36 in Shumabit@UMI —
+      // 12-min silent gap during a Playwright/Chrome OAuth dance,
+      // ZERO reactor-state events logged for that chat in that
+      // window. User reported "no typing, no reactions". Adding
+      // this heartbeat fixes the silent-window class of UX gap
+      // without changing agent behavior.
+      const VISIBILITY_HEARTBEAT_MS = 30 * 1000;
+      const armVisibilityTimer = () => {
+        if (visibilityTimer) clearInterval(visibilityTimer);
+        visibilityTimer = setInterval(() => {
+          if (!entry.pendingQueue.includes(pending)) {
+            // Pending no longer in queue → resolved/rejected/dropped.
+            // Defensive: clear ourselves even though clearTimers()
+            // SHOULD have been called.
+            if (visibilityTimer) { clearInterval(visibilityTimer); visibilityTimer = null; }
+            return;
+          }
+          const r = pending.context?.reactor;
+          if (r && typeof r.heartbeat === 'function') {
+            try { r.heartbeat(); } catch { /* defensive */ }
+          }
+        }, VISIBILITY_HEARTBEAT_MS);
+        visibilityTimer.unref?.();
+      };
+
       const clearTimers = () => {
         if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
         if (maxTimer) { clearTimeout(maxTimer); maxTimer = null; }
+        if (visibilityTimer) { clearInterval(visibilityTimer); visibilityTimer = null; }
       };
 
       const pending = {
@@ -728,6 +775,8 @@ class ProcessManagerSdk {
           maxTurnMs,
         );
         pending.maxTimer = maxTimer;
+        // rc.58: arm the visibility heartbeat at activation.
+        armVisibilityTimer();
         try { context?.onActivate?.(); }
         catch (err) { this.logger.error?.(`[${entry.label}] onActivate: ${err.message}`); }
       };

package/lib/replay-window.js

@@ -0,0 +1,53 @@
+/**
+ * rc.57: pure resolver for the boot-replay window in milliseconds.
+ *
+ * Lifted out of polygram.js's main() so the derivation rule can be
+ * unit-tested without spinning up the daemon.
+ *
+ * Precedence:
+ *   1. config.bot.replayWindowMs — explicit operator override (any
+ *      positive integer in ms).
+ *   2. Auto-derive from max(maxTurn) × 1.2 across all configured chats
+ *      (and defaults.maxTurn). Reasoning: if a chat allows turns up to
+ *      maxTurn seconds, an interrupted turn could be that old when
+ *      polygram restarts; replay window should outlast it. ×1.2 adds
+ *      buffer.
+ *   3. If no maxTurn is configured anywhere, return undefined (db.js
+ *      uses its 3-min default).
+ *
+ * Floor at 3 min (legacy default — never tighter than what we shipped
+ * before). Cap at 2h (sanity bound — replaying anything older is
+ * almost certainly stale work the user already moved on from).
+ *
+ * Discovery: msg 151 in Shumabit@UMI thread :24 (chat -1003369922517)
+ * was sent 2026-05-05 01:55:14, polygram restarted for rc.56 at
+ * 02:17 (22 min later). Pre-rc.57 the 3-min default discarded msg 151
+ * as too old; the agent's 7-hour Xero-template-build task was
+ * abandoned silently. Shumabit@UMI has maxTurn=3600 (60 min); 1.2×
+ * = 72 min replay window now keeps long turns alive across deploys.
+ */
+
+'use strict';
+
+const FLOOR_MS = 3 * 60 * 1000;        // 3 min
+const CAP_MS = 2 * 60 * 60 * 1000;     // 2 h
+const BUFFER = 1.2;                    // ×
+
+function resolveReplayWindowMs(config) {
+  const explicit = Number(config?.bot?.replayWindowMs);
+  if (Number.isInteger(explicit) && explicit > 0) return explicit;
+  const chatMaxes = Object.values(config?.chats || {})
+    .map((c) => Number(c?.maxTurn) || 0);
+  const defaultMax = Number(config?.defaults?.maxTurn) || 0;
+  const maxTurnSec = Math.max(0, ...chatMaxes, defaultMax);
+  if (maxTurnSec === 0) return undefined;
+  const derivedMs = Math.round(maxTurnSec * BUFFER * 1000);
+  return Math.max(FLOOR_MS, Math.min(CAP_MS, derivedMs));
+}
+
+module.exports = {
+  resolveReplayWindowMs,
+  FLOOR_MS,
+  CAP_MS,
+  BUFFER,
+};

package/lib/typing-indicator.js

@@ -19,7 +19,12 @@
  * handful of 401s, not worth persisting.
  */
 
-const DEFAULT_INTERVAL_MS = 4000;
+// rc.58: tightened from 4000 → 3000ms. Telegram's typing indicator
+// expires after ~5s; a 4s interval left a 1s margin where any tick
+// delay (event loop pressure, network blip, sandbox throttling) could
+// produce a brief visible flicker. 3s gives 2s margin and reduces
+// flicker risk on long silent SDK turns.
+const DEFAULT_INTERVAL_MS = 3000;
 const DEFAULT_MAX_CONSECUTIVE_401 = 10;
 const DEFAULT_MAX_BACKOFF_MS = 300_000; // 5 min — matches OpenClaw
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.8.0-rc.56",
+  "version": "0.8.0-rc.58",
   "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

@@ -66,6 +66,8 @@ const { createReactionManager, classifyToolName } = require('./lib/status-reacti
 const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
 const { classify: classifyError, isTransientHttpError } = require('./lib/error-classify');
 const { createAutoResumeTracker, isAutoResumable } = require('./lib/auto-resume');
+const { resolveReplayWindowMs } = require('./lib/replay-window');
+const { validateIpcFileParam } = require('./lib/ipc-file-validator');
 const {
   createStore: createApprovalsStore,
   matchesAnyPattern: matchesApprovalPattern,
@@ -1404,6 +1406,13 @@ async function handleSendOverIpc(req) {
     throw new Error(`chat not owned by ${BOT_NAME}: ${chatId}`);
   }
 
+  // rc.58: catch the most common file-upload mistakes before Telegram
+  // rejects with a confusing error. validateIpcFileParam returns a
+  // human-readable error string when the file param is malformed,
+  // null otherwise.
+  const fileParamErr = validateIpcFileParam(method, params);
+  if (fileParamErr) throw new Error(fileParamErr);
+
   const sendRes = await tg(bot, method, params, {
     source: source || 'ipc',
     botName: BOT_NAME,
@@ -3654,7 +3663,13 @@ async function pollBot(bot) {
           const chatId = m.chat.id.toString();
           const chatConfig = config.chats[chatId];
           const threadId = m.message_thread_id?.toString();
-          const topicName = threadId && chatConfig?.topics?.[threadId] ? chatConfig.topics[threadId] : threadId;
+          // rc.57: use getTopicName() helper which handles BOTH legacy string
+          // form and rc.48 object form. Pre-rc.57 the direct lookup
+          // `chatConfig.topics[threadId]` template-literal'd into "[object Object]"
+          // because rc.48 topics are objects like {name:"Music",agent:"...",...}.
+          const topicName = threadId
+            ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
+            : null;
           const chatLabel = chatConfig?.name || chatId;
           const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
           console.log(`[${BOT_NAME}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
@@ -4166,18 +4181,25 @@ async function main() {
   // Boot replay: re-dispatch any inbound turns that were interrupted by
   // the previous polygram's shutdown or crash. These are rows marked
   // 'dispatched', 'processing', or 'replay-pending' (set by the SIGTERM
-  // handler) — all within the last `replayWindowMs` (default 3 min) so
-  // we don't resurrect ancient work. Override via
-  // `config.bot.replayWindowMs` for ops tuning. Dedupe against
-  // already-sent outbound replies in case the previous instance DID
-  // answer before dying.
+  // handler) — all within the last `replayWindowMs` so we don't
+  // resurrect ancient work. Dedupe against already-sent outbound
+  // replies in case the previous instance DID answer before dying.
+  //
+  // rc.57: auto-derive replayWindowMs from max(maxTurn) * 1.2 when not
+  // explicitly set. Pre-rc.57 the default was 3 min — but chats with
+  // long agent tasks (Shumabit@UMI maxTurn=3600 = 60 min) would have
+  // their interrupted turns silently dropped because the turn was
+  // typically older than 3 min when polygram restarted. Discovery
+  // context: msg 151 in Shumabit@UMI thread :24 on 2026-05-05 was
+  // sent at 01:55:14, polygram restarted for rc.56 at 02:17 (22 min
+  // later). msg 151 was 'replay-pending' but boot-replay's 3-min
+  // window discarded it; the agent's 7-hour Xero task was abandoned.
+  // Auto-derive: 1.2 × max(chatConfig.maxTurn) across all chats,
+  // floored at 3 min (legacy default), capped at 2 hours (sanity).
   try {
     const chatIds = Object.keys(config.chats);
     if (chatIds.length > 0) {
-      const replayWindowMs = (() => {
-        const v = Number(config.bot?.replayWindowMs);
-        return (Number.isInteger(v) && v > 0) ? v : undefined; // undefined → use db.js default
-      })();
+      const replayWindowMs = resolveReplayWindowMs(config);
       const candidates = db.getReplayCandidates({ chatIds, ...(replayWindowMs && { olderThanMs: replayWindowMs }) });
       let replayed = 0;
       let skipped = 0;

package/skills/polygram-send/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: polygram-send
+description: Send messages, photos, documents, or stickers from a script (or from agent Bash) into the same Telegram chat the bot is in. Use when an agent or cron job needs to post a file, photo, or out-of-band text to a polygram chat — typically Xero invoices (PDF/.docx), generated reports, screenshots, or status pings tied to long-running work. Do NOT use for normal turn replies (those go through the agent's text reply, polygram delivers automatically). Do NOT use Telegram MCP — polygram-send is the supported path.
+---
+
+# polygram-send
+
+Polygram exposes a per-bot Unix socket at `/tmp/polygram-<bot>.sock`. Authorized callers (same UID, with the per-bot secret) can send Telegram API methods through it. Polygram routes them to the live bot connection, logs them in the `messages` table, and applies markdown / chunking / dedup.
+
+This is the **supported path** for any agent or script that needs to deliver a file or out-of-band message into a polygram-managed chat. Telegram MCP is **not** wired up; agents that try to call Telegram directly will hit auth or routing issues.
+
+## When to use
+
+- Agent generated a file (PDF, .docx, image, etc.) and the user asked for it in chat
+- Cron job needs to post a status update to the relevant chat
+- Long-running work needs an out-of-turn nudge (e.g. "build finished, here's the artifact")
+
+## When NOT to use
+
+- Your normal text reply to the user — return text from the turn, polygram delivers it through the streamed reply path. Don't double-send.
+- Anything that needs the message attributed to "user" — IPC always sends as the bot.
+- The Telegram MCP — explicitly NOT supported. Polygram blocks outbound message routing through anything other than its own bridge.
+
+## Allowed methods
+
+Polygram's IPC accepts (and only these):
+
+```
+sendMessage
+sendPhoto
+sendDocument
+sendSticker
+sendChatAction
+editMessageText
+setMessageReaction
+```
+
+Anything else → `method not allowed` rejection.
+
+## Usage from Bash (one-liner pattern)
+
+The lightest path is a `node -e` invocation that requires `polygram/lib/ipc-client`:
+
+```bash
+node -e '
+const { tell } = require("/Users/shumabit/.npm-global/lib/node_modules/polygram/lib/ipc-client");
+(async () => {
+  const r = await tell("shumabit", "sendDocument", {
+    chat_id: "-1003369922517",
+    message_thread_id: 24,
+    document: { source: "/absolute/path/to/invoice.docx" },
+    caption: "Artisan April invoice — ฿3,562.00",
+  }, { source: "agent:xero-invoice" });
+  console.log(JSON.stringify(r));
+})().catch(e => { console.error(e.message); process.exit(1); });
+'
+```
+
+Replace `shumabit` with `umi-assistant` or `shumorobot` for the other daemons. The `polygram` package path is wherever it was installed globally (run `npm root -g` to confirm).
+
+## Critical: how to pass `document` (and `photo`)
+
+For **sendDocument** and **sendPhoto**, the `document` (or `photo`) field has THREE valid forms. Pass the wrong one and Telegram rejects.
+
+### ✅ Local file path via `{ source: "/abs/path" }` — preferred
+
+```js
+document: { source: "/Users/shumabit/work/invoice.docx" }
+```
+
+This uses grammy's `InputFile` envelope. Polygram → grammy → multipart upload → Telegram. Works for any local file ≤50 MB. **Use this for any file you just generated.**
+
+### ✅ Public HTTPS URL — for files already hosted publicly
+
+```js
+document: "https://cdn.example.com/invoice.pdf"
+```
+
+Telegram fetches the URL directly. Must be **publicly reachable from Telegram's servers** (i.e. a public CDN, S3 bucket, or hosted endpoint). NOT localhost. NOT IP addresses Telegram can't reach. NOT HTTP — must be HTTPS.
+
+### ✅ Telegram `file_id` — for files Telegram has already seen
+
+```js
+document: "BAADAQADwAADBREAAVoQOnEZmRRJpmcE"
+```
+
+Re-use a file that polygram (or any bot) previously uploaded. Cheapest by far — no upload cost.
+
+### ❌ Common failures
+
+```js
+// WRONG: localhost URL — Telegram can't reach your Mac
+document: "http://localhost:8080/file.pdf"
+
+// WRONG: HTTP (not HTTPS) URL — Telegram requires HTTPS for URL form
+document: "http://cdn.example.com/file.pdf"
+
+// WRONG: malformed port (double colon, alpha chars)
+document: "http://host::8080/file.pdf"
+
+// WRONG: bare path string (Telegram will treat as a URL and reject)
+document: "/Users/shumabit/work/invoice.docx"
+```
+
+If you generated a file locally, ALWAYS use the `{ source: "/abs/path" }` form — never wrap it in a URL.
+
+## Picking the right `chat_id` and `message_thread_id`
+
+The chat the bot lives in is in `~/polygram/config.json` (shumabit-side) or `~/.polygram/config.json` (ivanshumkov-side). Each chat has:
+
+- `chat_id` — the Telegram numeric ID (negative for groups, positive for DMs)
+- `topics` — optional dict of `thread_id` → `{ name, ... }` (rc.48 form)
+
+For threaded chats (where `chatConfig.isolateTopics === true` or topics are listed), pass `message_thread_id: <number>` to land in the right topic. Without it, the message goes to the chat's General topic.
+
+**Don't hardcode thread IDs.** Read the current conversation's threadId from your invocation context, OR query the most recent inbound message in the relevant topic before sending. Hardcoding leaks state across deploys (the agent's view of "what topic we're in" can stale-bind to an old thread).
+
+## Source label
+
+Polygram tags every IPC send with a `source` string for forensics. Default is `cron:<scriptname>` if you don't pass one. **Always pass an explicit `source` from agent Bash** so it's visible in `messages.source` and forensic queries can attribute reliably:
+
+```js
+{ source: "agent:xero-invoice" }              // Xero workflow
+{ source: "agent:rekordbox-import-summary" }  // music-curation outputs
+{ source: "agent:status-ping" }               // generic out-of-turn update
+```
+
+Without an explicit source, the call shows up as `cron:unknown` and forensics can't tell whether it was a real cron job or an agent — which led to actual misdiagnosis on 2026-05-05 (rc.58 incident).
+
+## Captions
+
+`caption` accepts up to 1024 chars (vs 4096 for `sendMessage`). Polygram's lib/telegram-format.js handles markdown escape; agents passing markdown captions don't need to pre-escape.
+
+For long descriptions, send the file with a short caption + follow up with a separate `sendMessage` for the full text. Don't try to cram a long description into the caption.
+
+## Auth
+
+The IPC socket validates a per-bot secret (`/tmp/polygram-<bot>.secret`, mode 0600, same UID readable). `tell()` reads it automatically. Cross-user / cross-UID calls fail at socket-permission level. Cross-bot calls fail at chat ownership check (`chat_id must belong to this bot`).
+
+## Don't
+
+- Don't call this for normal text replies. Just emit text from the turn — polygram delivers it.
+- Don't use Telegram MCP.
+- Don't pass localhost URLs to `document`/`photo`.
+- Don't hardcode `message_thread_id` from previous sessions.
+- Don't omit `source` from agent-triggered sends.
+- Don't dedupe yourself — polygram's outbound dedupe + retry is already wired.
+
+## Related
+
+- IPC server: `lib/ipc-server.js` — handler registration, secret validation
+- IPC client: `lib/ipc-client.js` — `tell()`, `call()`
+- IPC method allowlist: `polygram.js` `IPC_SEND_ALLOWED_METHODS`
+- Smoke test: `scripts/ipc-smoke.js`