polygram 0.20.1 → 0.20.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "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",

package/lib/prompt.js

@@ -5,23 +5,37 @@
  * Telegram payload → polygram DB → unresolvable marker.
  */
 
+const { pickBackend } = require('@shumkov/orchestra');
+
+function resolvePromptBackend({ config, chatId, threadId = null }) {
+  return pickBackend({
+    config,
+    chatId: String(chatId),
+    threadId: threadId == null || threadId === '' ? null : String(threadId),
+    pmDefault: 'sdk',
+  });
+}
+
 /**
  * The <polygram-info> preamble. Sticker guidance is included ONLY when this bot
  * has a sticker set loaded (`stickerEmojis` non-empty) — a bot with no stickers.json
  * must not be told to emit stickers it doesn't have. The emoji list is the bot's OWN
  * pack (its emojiToSticker keys), not a hard-coded set, so it always matches reality.
  *
- * @param {{ stickerEmojis?: string[] }} [opts]
+ * @param {{ stickerEmojis?: string[], backend?: 'sdk'|'cli' }} [opts]
  */
-function polygramInfo({ stickerEmojis = [] } = {}) {
+function polygramInfo({ stickerEmojis = [], backend = 'sdk' } = {}) {
   const hasStickers = stickerEmojis.length > 0;
+  const deliveryContract = backend === 'cli'
+    ? `You are connected via a Telegram daemon (polygram) in channels mode. Inline final text is invisible to the Telegram user. For every user-visible response, you MUST call \`mcp__polygram-bridge__reply\` within this turn. Only a successful reply-tool receipt proves delivery. Do not claim something was already sent or posted above based only on the transcript; transcript content is not a delivery receipt. If delivery is uncertain, send it now with the reply tool.`
+    : `You are connected via a Telegram daemon (polygram). Just reply with text — polygram delivers your response automatically. Do NOT use Telegram MCP tools.`;
   const emojiLine = hasStickers
     ? `Single emoji reply = auto-converted: ${stickerEmojis.join('')} become your stickers, any other emoji (🔥👍💪❤️) becomes a reaction on the user's message.`
     : `Single emoji reply = auto-converted to a reaction on the user's message (any Telegram emoji: 🔥👍💪❤️ …).`;
   const stickerTag = hasStickers
     ? `\n- \`[sticker:NAME]\` anywhere in your reply sends that sticker after the text. NAME must match polygram's sticker map.`
     : '';
-  return `You are connected via a Telegram daemon (polygram). Just reply with text — polygram delivers your response automatically. Do NOT use Telegram MCP tools.
+  return `${deliveryContract}
 ${emojiLine}
 Inline tags (rc.63):${stickerTag}
 - \`[react:EMOJI]\` anywhere in your reply adds that emoji as a reaction on the user's message. Use any Telegram-supported emoji (👍 🔥 ❤️ 🎉 😢 …). Only the FIRST [react:] tag in a reply is applied; additional ones are dropped.
@@ -182,8 +196,9 @@ function buildVoiceTags(attachments) {
  * @param {string} params.sessionCtx - session context file contents (optional)
  * @param {Array} params.attachments - downloaded attachments
  * @param {Object} params.replyTo - input for buildReplyToBlock (optional)
+ * @param {'sdk'|'cli'} params.backend - delivery contract for the selected process backend
  */
-function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], replyTo = null, polygramHistory = '', stickerEmojis = [] }) {
+function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], replyTo = null, polygramHistory = '', stickerEmojis = [], backend = 'sdk' }) {
   const chatId = msg.chat.id.toString();
   const msgId = msg.message_id.toString();
   const user = msg.from?.first_name || msg.from?.username || 'Unknown';
@@ -207,7 +222,7 @@ function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], r
   if (polygramHistory) {
     prompt += polygramHistory + '\n\n';
   }
-  prompt += `<polygram-info>${polygramInfo({ stickerEmojis })}</polygram-info>\n\n`;
+  prompt += `<polygram-info>${polygramInfo({ stickerEmojis, backend })}</polygram-info>\n\n`;
 
   const replyBlock = buildReplyToBlock(replyTo);
   const attachmentTags = buildAttachmentTags(attachments);
@@ -225,6 +240,7 @@ function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], r
 }
 
 module.exports = {
+  resolvePromptBackend,
   xmlEscape,
   truncateReplyText,
   buildReplyToBlock,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "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": {
@@ -63,7 +63,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.123",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@shumkov/orchestra": "^0.4.2",
+    "@shumkov/orchestra": "0.4.3",
     "better-sqlite3": "^12.9.0",
     "grammy": "^1.42.0",
     "markdown-it": "^14.1.1",

package/polygram.js

@@ -27,7 +27,7 @@ const dbClient = require('./lib/db');
 const {
   migrateJsonToDb, getClaudeSessionId, resolveSessionForSpawn,
 } = require('./lib/db/sessions');
-const { buildPrompt } = require('./lib/prompt');
+const { buildPrompt, resolvePromptBackend } = require('./lib/prompt');
 const { filterAttachments, resolveFileCaps, resolveMaxFileOverride, MAX_TOTAL_BYTES } = require('./lib/attachments');
 // 0.9.0: SDK ProcessManager is the only pm. CLI pm
 // (lib/process-manager.js) deleted in commit 6.
@@ -430,6 +430,7 @@ function formatPrompt(msg, sessionCtx, attachments = [], { sessionKey = null } =
     attachments,
     replyTo: resolveReplyTo(msg),
     polygramHistory,
+    backend: resolvePromptBackend({ config, chatId, threadId }),
     // Only advertise stickers this bot actually has — empty for a bot with no
     // sticker set, so its prompt never mentions stickers.
     stickerEmojis: Object.keys(emojiToSticker),

package/skills/polygram-send/SKILL.md

@@ -1,25 +1,45 @@
 ---
 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.
+description: Choose the correct polygram delivery path for SDK turns, CLI/channels turns, and detached scripts. Use IPC for cron jobs or genuinely out-of-turn sends; use the reply MCP for interactive CLI text and files; return inline text for interactive SDK replies.
 ---
 
 # 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.
+This is the **supported IPC path** for a detached script that needs to deliver a file or out-of-band message into a polygram-managed chat. Interactive turns have backend-specific delivery paths described below. Generic Telegram MCP is not wired up; CLI/channels turns use polygram's own reply MCP instead.
 
-## When to use
+## Choose exactly one delivery lane
 
-- Agent generated a file (PDF, .docx, image, etc.) and the user asked for it in chat
+### SDK interactive turn
+
+Return the user-visible reply as inline assistant text. Polygram delivers it through the streamed SDK reply path. Do not also call the reply MCP or IPC, because that duplicates the message.
+
+Conversation transcript text does not prove an earlier reply reached Telegram. Do not claim a report was "already sent" or "posted above" based only on transcript history. If delivery is uncertain, include the content in the current inline reply.
+
+### CLI/channels interactive turn
+
+Inline final text is not delivered to Telegram. Send every user-visible text reply through `mcp__polygram-bridge__reply` within the turn. Attach generated files through that tool's `files` array. Do not use IPC for an interactive text or file reply.
+
+Only a successful reply-tool receipt proves delivery. Transcript text and an attempted call without a successful receipt do not. If delivery is uncertain, call the reply tool now instead of claiming the message was sent earlier.
+
+### Cron or detached script
+
+Use the `polygram-send` IPC client described below. This lane is for code running outside an interactive turn, including cron jobs, detached background scripts that generated files, and genuinely out-of-turn status updates. Check the IPC response and treat only a successful response as proof of delivery.
+
+## When to use IPC
+
+- A detached script generated a file (PDF, .docx, image, etc.) after the interactive turn ended
 - 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
+## When NOT to use IPC
 
-- Your normal text reply to the user — return text from the turn, polygram delivers it through the streamed reply path. Don't double-send.
+- A normal SDK text reply — return inline text.
+- A normal CLI/channels text reply — use `mcp__polygram-bridge__reply`.
+- A CLI/channels file reply during an interactive turn — pass absolute paths in the reply tool's `files` array.
 - 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.
+- Generic Telegram MCP — it is not a polygram delivery path.
 
 ## Allowed methods
 
@@ -139,8 +159,9 @@ The IPC socket validates a per-bot secret (`/tmp/polygram-<bot>.secret`, mode 06
 
 ## 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 use IPC for a normal interactive text reply; follow the SDK or CLI lane above.
+- Don't use generic Telegram MCP.
+- Don't infer successful delivery from transcript text.
 - 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.