polygram 0.12.0-rc.4 → 0.12.0-rc.7

package/config.example.json

@@ -4,6 +4,7 @@
   "bots": {
     "admin-bot": {
       "token": "REPLACE_WITH_BOT_TOKEN_FROM_BOTFATHER",
+      "_comment_apiRoot": "Optional. Point grammy at a self-hosted Telegram Bot API server (e.g. 'http://localhost:8081' from a local `telegram-bot-api --local` process) to raise file send/receive limits from cloud's 50MB-out / 20MB-in to 2GB both ways. Omit for cloud Telegram (default, unchanged). The server is a separate localhost-only companion daemon — see docs/0.12.0-file-send.md.",
       "allowConfigCommands": true,
       "_comment_adminChatId": "Required when allowConfigCommands is true for pairing commands (/pair-code, /pairings, /unpair) to work. These grant cross-chat trust and are gated to the admin chat only.",
       "adminChatId": "123456789",

package/lib/attachments.js

@@ -22,8 +22,13 @@
  *     extension — the fallback only kicks in when MIME is unhelpful.
  */
 
-const MAX_FILE_BYTES = 10 * 1024 * 1024;
-const MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+// Inbound (user → bot) per-file cap. Telegram's cloud Bot API hard-caps
+// bot file DOWNLOADS (getFile) at 20 MB, so 20 MB is the real ceiling on
+// cloud — raised from 10 MB so users can send larger tracks/docs. With a
+// self-hosted Bot API server (config.bot.apiRoot) the Telegram limit rises
+// to 2 GB; override per-bot via config.bot.maxInboundFileBytes if so.
+const MAX_FILE_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
 const MIME_ALLOW = [
   /^image\//, /^audio\//, /^video\//,
   /^application\/pdf$/, /^text\/plain$/,

package/lib/handlers/abort.js

@@ -42,13 +42,37 @@ function createHandleAbort({
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
     const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
-    const hadActive = !!proc?.inFlight;
+    let hadActive = !!proc?.inFlight;
 
     // Mark BEFORE killing: the 'close' event fires almost immediately
     // after interrupt, and the surrounding handleMessage's catch
     // needs to see the flag to skip the generic error-reply.
     if (hadActive) markSessionAborted(sessionKey);
 
+    // "Stop" incident (shumorobot Music, 2026-05-31 13:08): on the
+    // CliProcess/channels backend a turn resolves on the quiet-window
+    // after claude's last reply tool call (inFlight → false), but claude
+    // can still be working (subagent, long Bash). Keying the ack on
+    // inFlight alone made "Stop" say "Nothing to stop" while a subagent
+    // download churned. probeBusyState() reads the TUI "esc to interrupt"
+    // hint — the truthful signal — so detection, the abort mark, and the
+    // ack all agree. The probe result is logged below (forensics) so the
+    // heuristic can be refined against real states later. Channels analog
+    // of the (deleted) tmux hasBackgroundShell branch; typeof-guarded so
+    // it's a no-op on backends without it.
+    let busyProbe = null;
+    if (!hadActive && proc && typeof proc.probeBusyState === 'function') {
+      try {
+        busyProbe = await proc.probeBusyState();
+        if (busyProbe?.busy) {
+          hadActive = true;
+          markSessionAborted(sessionKey);
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] busy-probe failed: ${err.message}`);
+      }
+    }
+
     // Bug 1 (incident 2026-05-18): "Stop" was turn-scoped — it only
     // looked at an in-flight TURN. But the agent can leave a DETACHED
     // background shell running (a `run_in_background:true` Bash) that
@@ -87,6 +111,19 @@ function createHandleAbort({
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
       killed_background_shell: killedBackgroundShell,
+      // "Stop" incident forensics: the raw busy-probe signals at decision
+      // time. Lets us query, across real aborts, where the esc-hint /
+      // inFlight / pending-turn signals agreed vs diverged and refine the
+      // heuristic later. null when no probe ran (turn was already inFlight,
+      // or the backend has no probeBusyState).
+      busy_probe: busyProbe ? {
+        busy: busyProbe.busy,
+        streaming: busyProbe.streaming,
+        in_flight: busyProbe.inFlight,
+        pending_turns: busyProbe.pendingTurns,
+        captured: busyProbe.captured,
+        pane_tail: busyProbe.paneTail,
+      } : null,
       trigger: cleanText.slice(0, 40),
     });
 

package/lib/ipc/file-validator.js

@@ -50,7 +50,14 @@ 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
+  // { source: '/abs/path' } envelope — now coerced to a grammy InputFile in
+  // tg() (coerceFileParams). Validate it has a usable absolute source, else
+  // pass through (Buffer / stream / InputFile shapes).
+  if (val && typeof val === 'object' && typeof val.source === 'string') {
+    if (val.source.length === 0) return `polygram IPC: ${fileParam}.source is empty`;
+    return null;
+  }
+  if (typeof val !== 'string') return null;       // Buffer/InputFile/etc — pass through
   if (val.length === 0) return `polygram IPC: ${fileParam} is empty`;
 
   const looksUrl = /^(https?|ftp):\/\//i.test(val);

package/lib/process/channels-tool-dispatcher.js

@@ -203,7 +203,10 @@ function createChannelsToolDispatcher({
             const fieldName = isImage ? 'photo' : 'document';
             const params = {
               chat_id: chatId,
-              [fieldName]: { source: check.resolved },
+              // { source } envelope → grammy InputFile in tg()'s coerceFileParams.
+              // Pre-fix this bare object reached grammy unrecognized and every
+              // upload 400'd with "Wrong port number" (file-send never worked).
+              [fieldName]: { source: check.resolved, filename: path.basename(check.resolved) },
             };
             if (threadId) params.message_thread_id = threadId;
             await send(bot, method, params, { source: 'channels-tool-dispatcher', sessionKey });

package/lib/process/cli-process.js

@@ -48,6 +48,10 @@ const { Process, UnsupportedOperationError } = require('./process');
 const { ChannelsBridgeServer } = require('./channels-bridge-server');
 const { writeHookFiles, removeHookFiles } = require('./hook-settings');
 const { createHookTail } = require('./hook-event-tail');
+// File-send staging: reuse the dispatcher's allowlist root so the dir we
+// create exactly matches the realpath the validator accepts (no /tmp vs
+// /private/tmp drift — one of the original Music-topic failures).
+const { DEFAULT_ATTACHMENT_BASE } = require('./channels-tool-dispatcher');
 const { runStartupGate } = require('../tmux/startup-gate');
 const { POLYGRAM_DISPLAY_HINT } = require('../telegram/display-hint');
 
@@ -297,6 +301,23 @@ class CliProcess extends Process {
     // permit files under the agent's workspace.
     this.sessionCwd = opts.cwd || null;
 
+    // File-send staging dir (2026-06 file-send feature). The dispatcher
+    // allowlist always permits <DEFAULT_ATTACHMENT_BASE>/<sessionKey>/, but
+    // nothing ever CREATED it — so claude's reply(files) attempts at
+    // /tmp/polygram-attachments failed (dir absent / realpath mismatch) and
+    // it flailed across other paths. Create it here and surface it to the
+    // prompt so claude has one blessed, always-allowed place to stage a file
+    // before sending. realpathSync so the stored path matches what the
+    // validator resolves (the /tmp ↔ /private/tmp fix).
+    try {
+      const dir = path.join(DEFAULT_ATTACHMENT_BASE, String(this.sessionKey));
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      this.attachmentStagingDir = fs.realpathSync(dir);
+    } catch (err) {
+      this.attachmentStagingDir = null;
+      this.logger.warn?.(`[${this.label}] channels: staging dir create failed: ${err.message}`);
+    }
+
     // Opaque random token for socket filename — do NOT leak sessionKey to /tmp.
     const socketToken = crypto.randomBytes(16).toString('hex');
     this.sockPath = path.join(os.tmpdir(), `polygram-${socketToken}.sock`);
@@ -598,6 +619,27 @@ class CliProcess extends Process {
       'Internal tool calls (Bash, Edit, Write, Read, etc.) are fine to use',
       'as normal — only the FINAL user-visible message needs to go through',
       'the reply tool.',
+      '',
+      '### Sending FILES (tracks, images, docs) to the user',
+      '',
+      'The `mcp__polygram-bridge__reply` tool takes an optional `files` array of',
+      'absolute paths. This is the ONLY way to send a file. Do NOT use Bash,',
+      'curl, the Telegram Bot API, or polygram-ipc to send files — those fail.',
+      '',
+      ...(this.attachmentStagingDir ? [
+        `To send a file: COPY it into the staging dir \`${this.attachmentStagingDir}\`,`,
+        'then call reply with its absolute path, e.g.:',
+        `  reply(chat_id="<id>", text="Here's the track", files=["${this.attachmentStagingDir}/track.flac"])`,
+        'polygram auto-deletes staged files after the turn — you do not need to clean up.',
+        'You may also send directly from the agent workspace (cwd); other paths are rejected.',
+      ] : [
+        'Copy the file somewhere under your workspace (cwd) and pass its absolute',
+        'path in `files`. Paths outside the workspace are rejected for safety.',
+      ]),
+      '',
+      'Telegram caps bot file uploads at 50 MB (cloud). For larger lossless',
+      'audio, convert to FLAC/MP3 under 50 MB first, or tell the user it exceeds',
+      'the limit. Images go as photos; everything else as documents.',
     ].join('\n'));
 
     // Parity audit P6: honor isolateUserConfig — mirrors tmux pattern at
@@ -1203,6 +1245,27 @@ class CliProcess extends Process {
     pending.resolve(result);
     this.emit('result', { subtype: 'success' }, { streamText: text });
     this.emit('idle');
+    // File-send staging auto-purge (your choice — no "claude must delete").
+    // Once the LAST turn settles, wipe the staging dir's contents so files
+    // claude copied in to send don't accumulate on disk across turns. Only
+    // when fully idle, so a file staged for a still-pending concurrent turn
+    // isn't yanked mid-send.
+    if (this.pendingTurns.size === 0) this._purgeStagingDir();
+  }
+
+  /**
+   * Empty the per-session file-send staging dir (keep the dir itself).
+   * Best-effort; never throws. Called when the session goes idle and on kill.
+   */
+  _purgeStagingDir() {
+    if (!this.attachmentStagingDir) return;
+    let entries;
+    try { entries = fs.readdirSync(this.attachmentStagingDir); }
+    catch { return; }
+    for (const name of entries) {
+      try { fs.rmSync(path.join(this.attachmentStagingDir, name), { recursive: true, force: true }); }
+      catch { /* best-effort */ }
+    }
   }
 
   // ─── public Process API ──────────────────────────────────────────
@@ -1394,6 +1457,63 @@ class CliProcess extends Process {
     this._interruptGraceTimer.unref?.();
   }
 
+  /**
+   * Is claude actually still working, regardless of the resolved-turn flag?
+   *
+   * "Stop" incident (shumorobot Music, 2026-05-31 13:08): the channels
+   * backend resolves a turn on the quiet-window after claude's last reply
+   * tool call (inFlight → false), but claude can keep working afterwards
+   * (a subagent, a long Bash). The abort handler keyed its ack on inFlight
+   * alone, so "Stop" said "Nothing to stop" one second after the bot said
+   * "On it — downloading…" while a subagent churned.
+   *
+   * The TUI prints "esc to interrupt" (STREAMING_HINT_RE) continuously
+   * whenever claude is busy — capture-pane is the truthful signal, the
+   * channels analog of the (deleted) tmux hasBackgroundShell() probe.
+   *
+   * Returns a STRUCTURED probe (not just a boolean) so the abort path can
+   * log the raw signals — pane tail + flags — to the events DB. That lets
+   * us later characterize which states the heuristic gets right/wrong and
+   * refine it (e.g. add signals beyond the esc-hint) without guessing.
+   *
+   * Never throws — a failed capture returns captured:false, busy:false.
+   *
+   * @returns {Promise<{busy:boolean, streaming:boolean, inFlight:boolean,
+   *   pendingTurns:number, captured:boolean, paneTail:(string|null)}>}
+   */
+  async probeBusyState() {
+    const base = {
+      busy: false, streaming: false,
+      inFlight: this.inFlight, pendingTurns: this.pendingTurns.size,
+      captured: false, paneTail: null,
+    };
+    if (this.closed || !this.tmuxSession || typeof this.runner?.captureWide !== 'function') {
+      return base;
+    }
+    let pane;
+    try {
+      pane = await this.runner.captureWide(this.tmuxSession);
+    } catch (err) {
+      this.logger.warn?.(`[${this.label}] channels: probeBusyState captureWide failed: ${err.message}`);
+      return base;
+    }
+    if (!pane) return base;
+    const streaming = STREAMING_HINT_RE.test(pane);
+    return {
+      ...base,
+      busy: streaming,
+      streaming,
+      captured: true,
+      paneTail: pane.slice(-200),
+    };
+  }
+
+  /** Boolean shorthand for probeBusyState().busy (abort-path convenience). */
+  async isBusy() {
+    const { busy } = await this.probeBusyState();
+    return busy;
+  }
+
   async kill(reason = 'kill') {
     if (this.closed) return;
     // Parity P19: re-entry guard for concurrent kill() calls. Mirrors
@@ -1804,6 +1924,12 @@ class CliProcess extends Process {
     if (this.botName && this.claudeSessionId) {
       try { removeHookFiles({ botName: this.botName, sessionId: this.claudeSessionId }); } catch {}
     }
+    // File-send staging: remove the whole per-session dir on kill (purge only
+    // empties it between turns; kill is end-of-life so drop it entirely).
+    if (this.attachmentStagingDir) {
+      try { fs.rmSync(this.attachmentStagingDir, { recursive: true, force: true }); } catch {}
+      this.attachmentStagingDir = null;
+    }
 
     this.emit('close', 0);
   }

package/lib/telegram/api.js

@@ -28,6 +28,7 @@ const {
   getRetryAfterMs,
 } = require('./format');
 const { isSafeToRetry, redactBotToken } = require('../error/net');
+const { coerceFileParams } = require('./input-file');
 
 // Topic deletion race: a user can delete a forum topic while a turn is in
 // flight, turning a valid `message_thread_id` into a 404. Telegram's error
@@ -112,6 +113,14 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   const chatId = params.chat_id != null ? String(params.chat_id) : null;
   const threadId = params.message_thread_id != null ? String(params.message_thread_id) : null;
 
+  // File-upload bug fix (2026-05-31): coerce a `{ source: '/abs/path' }`
+  // file param into a grammy InputFile so local-file uploads actually work.
+  // grammy doesn't recognize the bare envelope → it failed every send with
+  // "Wrong port number". Single choke point: fixes channels reply(files)
+  // AND the IPC send path at once. No-op for non-file methods / file_id /
+  // URL strings / existing InputFile instances.
+  coerceFileParams(method, params);
+
   // 0.7.4: empty-text short-circuit. Pre-fix, an empty params.text on
   // sendMessage/editMessageText reached Telegram and 400'd with
   // "message text is empty"; the row was marked failed and propagated

package/lib/telegram/input-file.js

@@ -0,0 +1,76 @@
+/**
+ * input-file — coerce file-upload params into grammy InputFile instances.
+ *
+ * The bug (2026-05-31, shumorobot Music): callers passed a Telegraf-style
+ * `{ source: '/abs/path' }` envelope as the file param (document/photo/…).
+ * grammy 1.x does NOT recognize that shape — it's not an InputFile, so
+ * grammy serializes it as a plain object and Telegram tries to read it as
+ * a URL/file_id, failing with "invalid file HTTP URL: Wrong port number".
+ * Result: file-send NEVER worked (channels reply(files) AND the IPC path
+ * both produced this exact error). The existing dispatcher test used a fake
+ * `send` and only asserted the METHOD, so it couldn't catch the bad shape.
+ *
+ * grammy uploads a local file only when the param is `new InputFile(path)`.
+ * This helper normalizes, at the single send choke point (tg()), the
+ * `{ source: <abs path> }` envelope → `new InputFile(path)`, leaving every
+ * other shape untouched:
+ *   - string file_id / https URL  → pass through (Telegram resolves)
+ *   - existing InputFile instance → pass through (already correct)
+ *   - Buffer / stream            → pass through (grammy handles)
+ *
+ * Only the explicit `{ source: string }` envelope is transformed — bare
+ * path strings are intentionally NOT coerced (a Telegram file_id is also a
+ * bare string; coercing would break sends-by-id).
+ */
+
+'use strict';
+
+const { InputFile } = require('grammy');
+
+// method → the params field that carries the file.
+const FILE_FIELD_BY_METHOD = {
+  sendPhoto: 'photo',
+  sendDocument: 'document',
+  sendAudio: 'audio',
+  sendVideo: 'video',
+  sendAnimation: 'animation',
+  sendVoice: 'voice',
+  sendVideoNote: 'video_note',
+};
+
+/**
+ * Return a grammy-uploadable value for a single file param, or the original
+ * value unchanged if it's not the `{ source }` envelope we coerce.
+ */
+function coerceFileValue(val) {
+  if (val && typeof val === 'object' && !(val instanceof InputFile)
+      && typeof val.source === 'string' && val.source.length > 0) {
+    // { source: '/abs/path' } | { source: 'https://…', filename } → InputFile
+    return new InputFile(val.source, val.filename);
+  }
+  return val;
+}
+
+/**
+ * Mutate `params` in place so its file field (if any) is grammy-uploadable.
+ * No-op for non-file methods and for params with no file field set.
+ *
+ * @param {string} method
+ * @param {object} params
+ * @returns {object} the same params object (for chaining)
+ */
+function coerceFileParams(method, params) {
+  if (!params || typeof params !== 'object') return params;
+  const field = FILE_FIELD_BY_METHOD[method];
+  if (!field) return params;
+  if (params[field] != null) {
+    params[field] = coerceFileValue(params[field]);
+  }
+  return params;
+}
+
+module.exports = {
+  coerceFileParams,
+  coerceFileValue,
+  FILE_FIELD_BY_METHOD,
+};

package/package.json

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

@@ -1672,9 +1672,23 @@ function shouldHandle(msg, chatConfig, botUsername) {
 }
 
 function createBot(token) {
+  // Optional self-hosted Telegram Bot API server. When config.bot.apiRoot is
+  // set (e.g. "http://localhost:8081" from a local `telegram-bot-api`
+  // process), grammy routes all Bot API calls there instead of
+  // api.telegram.org — which lifts file send/receive from cloud's 50 MB-out /
+  // 20 MB-in to 2 GB both ways. Omit it (default) → cloud Telegram, unchanged.
+  // The local server is a separate companion daemon; this is just the knob
+  // that points polygram at it. See docs/0.12.0-file-send.md.
+  const apiRoot = config.bot?.apiRoot;
   const bot = new Bot(token, {
-    client: { timeoutSeconds: 60 },
+    client: {
+      timeoutSeconds: 60,
+      ...(apiRoot ? { apiRoot } : {}),
+    },
   });
+  if (apiRoot) {
+    console.log(`[polygram] using local Telegram Bot API server: ${apiRoot} (2GB file limit)`);
+  }
   let botUsername = '';
   // Cached once @botUsername is known — was recompiling per inbound msg.
   let mentionRe = null;