polygram 0.7.6 → 0.7.8

package/.claude-plugin/plugin.json

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

@@ -8,7 +8,13 @@ const fs = require('fs');
 const path = require('path');
 const Database = require('better-sqlite3');
 
-const SCHEMA_VERSION = 8;
+// 0.7.8: bumped from 8 → 9. 0.7.6 added migration 009-turn-metrics.sql
+// but failed to bump SCHEMA_VERSION; the early-return on line ~36
+// skipped the migration loop on any DB already at user_version=8 (any
+// upgraded install) → turn_metrics table never created → INSERT prepare
+// at startup crashed polygram. Both 0.7.6 and 0.7.7 shipped with the
+// bug. Fixed by bumping the constant.
+const SCHEMA_VERSION = 9;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo

package/lib/error-classify.js

@@ -0,0 +1,290 @@
+/**
+ * Error classifier — maps any error from any source to a stable shape.
+ *
+ * Sources today (0.7.7): stream-json `result` events with error
+ * subtypes, child_process `'close'`/`'error'` event errors, idle
+ * timer fires, polygram-internal Errors with `err.code` set.
+ *
+ * Sources after 0.8.0 SDK migration: SDK iterator throws
+ * (`AbortError` named class plus plain `Error`s), `SDKResultMessage`
+ * with subtypes `error_during_execution` / `error_max_turns` /
+ * `error_max_budget_usd` / `error_max_structured_output_retries`,
+ * per-message `SDKAssistantMessage.error` subtypes
+ * (`authentication_failed` / `billing_error` / `rate_limit` /
+ * `invalid_request` / `server_error` / `unknown` / `max_output_tokens`),
+ * 5xx HTTP errors that bubble through the SDK transport.
+ *
+ * Returning the same shape regardless of transport means
+ * `errorReplyText` in polygram.js doesn't grow N branches every time
+ * a new error class shows up — we just add a row to PATTERNS or a
+ * `code:` short-circuit at the top.
+ *
+ * Layered ship order (per v4 plan §6.5.1):
+ *   - 0.7.7 (this file): transport-agnostic patterns and the public
+ *     `classify()` API. Polygram.js's `errorReplyText` consults this
+ *     module directly.
+ *   - Phase 1 of 0.8.0 (later): adds typed-code branches for
+ *     `INTERRUPTED`, plus SDK `error_max_structured_output_retries`,
+ *     plus per-message SDK error subtypes.
+ *   - Phase 2 of 0.8.0 (later): adds AUTO_RECOVER actions
+ *     (`reset_session` etc) so pm can self-heal stuck sessions
+ *     without waiting for the user to type /new.
+ */
+
+'use strict';
+
+// Substring/regex patterns matched against the error string. Order
+// is significant only when patterns overlap — `transient5xx` is last
+// because the others (auth/billing/format) carry their own status
+// codes too. First match wins.
+const PATTERNS = {
+  // Anthropic API rate limit (429) — "rate-limited", "Too Many
+  // Requests", token-bucket exhaustion text.
+  rateLimit:        /\b429\b|rate[_ ]?limit|too[_ ]many[_ ]requests|tokens? per minute/i,
+
+  // Billing / quota (402, "insufficient credit"). Fires before any
+  // model call when the workspace is out of funds.
+  billing:          /\b402\b|payment[_ ]required|billing|insufficient[_ ]credit/i,
+
+  // Auth: 401/403, OAuth token expiry, refresh failure. The 0.8.0
+  // plan ships an explicit auth-expired UX (admin-chat notify +
+  // pause); 0.7.7 just maps to a friendlier user message.
+  authExpired:      /\b401\b|\b403\b|unauthor(ized|ised)|forbidden|token[_ ]expired|oauth[_ ]token[_ ]refresh[_ ]failed/i,
+
+  // Context window exceeded — too many tokens for the model. Usually
+  // surfaces as `prompt is too long` from Anthropic; sometimes as
+  // generic "exceeds maximum context" depending on SDK version.
+  contextOverflow:  /context[_ ](window|length)|prompt[_ ]too[_ ]large|exceeds[_ ]maximum[_ ]context|prompt is too long/i,
+
+  // Role alternation / message ordering — fires when transcript has
+  // consecutive same-role messages or a tool_use without matching
+  // tool_result. Polygram doesn't generate these directly, but they
+  // can surface after an interrupted turn.
+  roleOrdering:     /role.*alternat|message[_ ]ordering|consecutive (user|assistant)/i,
+
+  // Tool call missing required `input` field. Indicates corrupted
+  // history; user-facing message tells them to /new. Word order
+  // varies across Anthropic SDK versions — accept either
+  // "input...missing" or "missing...input" within a tool_use mention.
+  missingToolInput: /tool[_ ]use.*(input.*missing|missing.*input)|missing tool call input|tool input required/i,
+
+  // Idle/wall-clock timeout from polygram's pm timers, OR
+  // model-side timeout. Mapped to a single class; user message is
+  // identical either way.
+  timeout:          /timed[_ ]out|deadline|idle with no Claude activity|wall-clock ceiling/i,
+
+  // Generic format/validation errors (400 with no other class
+  // matching). Rare in practice; included so we don't fall through
+  // to "unknown".
+  format:           /invalid[_ ]request|invalid[_ ]json|malformed|bad request/i,
+
+  // Transient HTTP (5xx upstream Anthropic outage / overload). Only
+  // these get retried by pm. 521-524/529 are Cloudflare codes seen
+  // when Anthropic's edge is degraded.
+  transient5xx:     /\b5(00|02|03|2[1-4]|29)\b|temporarily overloaded|server[_ ]error|service unavailable/i,
+};
+
+// User-facing message per kind. Polygram-style emoji + concise
+// action hint. `null` means "suppress the user-facing reply" (used
+// for INTERRUPTED inside the abort-grace window — the user already
+// saw their /stop ack).
+const USER_MESSAGES = {
+  rateLimit:        '⚠️ Rate-limited by Anthropic. Try again in a minute.',
+  billing:          '💳 Billing issue on Anthropic — operator needs to top up credits.',
+  authExpired:      '🔑 Claude auth expired. Operator has been notified.',
+  contextOverflow:  '📚 Conversation got too long. Send /new to start fresh.',
+  roleOrdering:     '⚠️ Conversation got into a tangled state. Try /new.',
+  missingToolInput: '⚠️ Session history looks corrupted. Try /new.',
+  timeout:          '⏳ I went quiet too long without finishing. Try resending or simplifying.',
+  format:           '⚠️ Invalid request format. Try rephrasing or /new.',
+  transient5xx:     '☁️ Anthropic is temporarily unavailable. Retrying once…',
+};
+
+// Auto-recovery actions for kinds where the session is irrecoverable
+// without a reset. Phase 2 of 0.8.0 wires `pm.resetSession()` to
+// these; 0.7.7 just exports the table for forward-compat.
+//
+// Values map to action names that pm understands:
+//   'reset_session' — close current Query, clear sessionId, fresh start
+//   (future) 'compact' — manual compact request, if SDK exposes it
+const AUTO_RECOVER = {
+  roleOrdering:     'reset_session',
+  contextOverflow:  'reset_session',
+  missingToolInput: 'reset_session',
+};
+
+// Typed-code short-circuits — set on errors polygram throws itself
+// (see lib/process-manager.js), not pattern-matched. Keep these in
+// sync with the codes pm emits.
+const CODES = {
+  // 0.7.6 (item H): queue cap drop. Pre-empts pattern matching so
+  // the queue-overflow message is exact, not classified.
+  QUEUE_OVERFLOW: {
+    kind: 'queueOverflow',
+    userMessage: '⏭ Couldn\'t keep up — this message was skipped while I was processing newer ones. Resend if it still matters.',
+    isTransient: false,
+    autoRecover: null,
+  },
+  // 0.8.0 Phase 1 will set this on pendings rejected via
+  // pm.interrupt(). Matched here so the abort-grace silence works
+  // before the SDK migration lands (pm could start setting it
+  // earlier as a no-op).
+  INTERRUPTED: {
+    kind: 'interrupted',
+    userMessage: null, // suppressed; user already saw the /stop ack
+    isTransient: false,
+    autoRecover: null,
+  },
+  // Phase 2 will set this when pm.resetSession() drains the queue
+  // for any reason (auto-recovery, /new, /reset, auth-expired).
+  RESET_SESSION: {
+    kind: 'resetSession',
+    userMessage: '✨ Started a fresh session.',
+    isTransient: false,
+    autoRecover: null,
+  },
+  // 0.8.0 auth-expired path — set on every pending the daemon
+  // rejects after a 401 surface. Distinct from authExpired pattern
+  // because it's polygram saying "I already noticed and paused"
+  // rather than "I just hit a 401 and am about to handle it".
+  AUTH_EXPIRED: {
+    kind: 'authExpired',
+    userMessage: '🔑 The bot needs re-auth. The operator has been notified. Try again in a few minutes.',
+    isTransient: false,
+    autoRecover: null,
+  },
+};
+
+/**
+ * Classify an error from any source.
+ *
+ * Accepts:
+ *   - Error / object with `code` / `message`
+ *   - SDKResultMessage with `subtype` and optional `error`
+ *   - SDKAssistantMessage.error (string subtype like 'rate_limit')
+ *   - plain string
+ *   - null/undefined (returns the 'unknown' shape)
+ *
+ * Returns an object with stable shape:
+ *   {
+ *     kind: 'rateLimit' | 'billing' | ... | 'unknown' | code-keyed kind,
+ *     userMessage: string | null,   // null means suppress reply
+ *     isTransient: boolean,         // true → pm should retry once
+ *     autoRecover: 'reset_session' | null,
+ *   }
+ */
+function classify(err) {
+  // Typed-code short-circuit takes priority over pattern matching.
+  // Errors polygram constructs internally (QUEUE_OVERFLOW etc.) set
+  // `err.code` so we don't depend on string content.
+  const code = err?.code;
+  if (code && CODES[code]) {
+    return { ...CODES[code] };
+  }
+
+  // SDKAssistantMessage.error is a short string code from a fixed
+  // union — match those directly, not via regex.
+  if (typeof err === 'string') {
+    const sdkMessageError = matchSdkMessageError(err);
+    if (sdkMessageError) return sdkMessageError;
+  }
+  if (err?.subtype && typeof err.subtype === 'string') {
+    const sdkResultSubtype = matchSdkResultSubtype(err.subtype);
+    if (sdkResultSubtype) return sdkResultSubtype;
+  }
+
+  const msg = extractMessage(err);
+  for (const [kind, re] of Object.entries(PATTERNS)) {
+    if (re.test(msg)) {
+      return {
+        kind,
+        userMessage: USER_MESSAGES[kind],
+        isTransient: kind === 'transient5xx' || kind === 'rateLimit',
+        autoRecover: AUTO_RECOVER[kind] ?? null,
+      };
+    }
+  }
+
+  // Fall-through: surface a snippet of the raw error so users at
+  // least know SOMETHING happened. Same shape as before, just
+  // routed through the classifier so callers get a uniform return.
+  const reason = msg.split('\n')[0].slice(0, 120);
+  return {
+    kind: 'unknown',
+    userMessage: `Hit a snag: ${reason || 'unknown error'}. Try resending.`,
+    isTransient: false,
+    autoRecover: null,
+  };
+}
+
+// Pull a string out of whatever shape the caller passed.
+function extractMessage(err) {
+  if (err == null) return '';
+  if (typeof err === 'string') return err;
+  if (err.message) return String(err.message);
+  if (err.error) return String(err.error);
+  return String(err);
+}
+
+// SDKAssistantMessage.error fields are a small fixed union
+// (sdk.d.ts:2343). Map directly so we don't depend on transport-
+// specific error text.
+const SDK_MESSAGE_ERROR_MAP = {
+  authentication_failed: 'authExpired',
+  billing_error:         'billing',
+  rate_limit:            'rateLimit',
+  invalid_request:       'format',
+  server_error:          'transient5xx',
+  unknown:               'unknown',
+  max_output_tokens:     'format', // closest match — model gave up
+};
+function matchSdkMessageError(s) {
+  const kind = SDK_MESSAGE_ERROR_MAP[s];
+  if (!kind) return null;
+  if (kind === 'unknown') return null; // fall through to pattern match
+  return {
+    kind,
+    userMessage: USER_MESSAGES[kind] ?? null,
+    isTransient: kind === 'transient5xx' || kind === 'rateLimit',
+    autoRecover: AUTO_RECOVER[kind] ?? null,
+  };
+}
+
+// SDKResultMessage.subtype values (sdk.d.ts:3121). Most are
+// terminal-error indicators that don't have a clean pattern equivalent.
+const SDK_RESULT_SUBTYPE_MAP = {
+  error_during_execution:           'unknown',
+  error_max_turns:                  'format',
+  error_max_budget_usd:             'billing',
+  error_max_structured_output_retries: 'format',
+};
+function matchSdkResultSubtype(s) {
+  if (s === 'success') return null;
+  const kind = SDK_RESULT_SUBTYPE_MAP[s];
+  if (!kind || kind === 'unknown') return null;
+  return {
+    kind,
+    userMessage: USER_MESSAGES[kind] ?? null,
+    isTransient: false, // result subtypes don't auto-retry; the
+                        // turn already burned its budget.
+    autoRecover: AUTO_RECOVER[kind] ?? null,
+  };
+}
+
+// True if pm's iteration loop should sleep and retry the user
+// message ONCE before giving up. Currently only transient5xx and
+// rateLimit. Per v4 plan §6.6 H1/M2, retry only fires when the
+// turn produced ZERO assistant messages (idempotency); pm checks
+// that flag, not this function.
+function isTransientHttpError(err) {
+  return classify(err).isTransient;
+}
+
+module.exports = {
+  classify,
+  isTransientHttpError,
+  PATTERNS,
+  USER_MESSAGES,
+  AUTO_RECOVER,
+  CODES,
+};

package/lib/process-manager.js

@@ -26,9 +26,19 @@
  */
 
 const { createInterface } = require('readline');
+const { isTransientHttpError } = require('./error-classify');
 
 const DEFAULT_CAP = 10;
 const DEFAULT_KILL_TIMEOUT_MS = 3000;
+// 0.7.7: transient HTTP retry. When Anthropic returns a 5xx (or 429
+// rate-limit) and the turn produced ZERO assistant messages so far,
+// pm sleeps and retries the user message ONCE before surfacing the
+// error to the user. Matches OpenClaw's
+// pi-embedded-Vt2x_Jl3.js:39210-39216 — "single retry, then surface".
+// Idempotency-protected: we only retry if no assistant content has
+// streamed (otherwise re-sending would replay tools that already ran).
+const DEFAULT_TRANSIENT_RETRY_DELAY_MS = 2500;
+const MAX_TRANSIENT_RETRIES = 1;
 // 0.7.6 (item H): hard cap on per-session pending queue depth.
 // Pre-fix, a chat with rapid-fire user messages (or a stuck Claude that
 // stops emitting `result`) could grow pendingQueue unbounded — each
@@ -328,9 +338,14 @@ class ProcessManager {
         // pending. Fire onFirstStream ONCE, regardless of whether the
         // assistant message has text or only tool_use blocks (some turns
         // emit tool_use first with no preamble).
-        if (added || (Array.isArray(event.message?.content)
-            && event.message.content.some((b) => b?.type === 'tool_use'))) {
+        const hasAssistantContent = !!added || (Array.isArray(event.message?.content)
+            && event.message.content.some((b) => b?.type === 'tool_use'));
+        if (hasAssistantContent) {
           head.fireFirstStream?.();
+          // 0.7.7: any assistant content (text OR tool_use) disqualifies
+          // the turn from transient-retry — re-sending the user prompt
+          // after this point would replay tools that already executed.
+          head.firstAssistantSeen = true;
         }
         // 0.7.6 (item F): accumulate usage + counters for turn telemetry.
         // The `result` event carries total_cost_usd + duration_ms but NOT
@@ -392,6 +407,66 @@ class ProcessManager {
       }
 
       if (event.type === 'result' && head) {
+        // 0.7.7: transient HTTP retry. If Anthropic returned a
+        // retryable error AND the turn produced ZERO assistant
+        // content yet AND we haven't already retried, sleep and
+        // re-write the prompt instead of resolving the pending.
+        // Idempotency: firstAssistantSeen guards against replaying
+        // tools that already ran.
+        const errSignal = event.error || event.subtype;
+        const isError = event.subtype !== 'success';
+        const shouldTransientRetry = isError
+          && !head.firstAssistantSeen
+          && head.transientRetries < MAX_TRANSIENT_RETRIES
+          && head.prompt != null
+          && isTransientHttpError({ message: errSignal, subtype: event.subtype });
+        if (shouldTransientRetry) {
+          head.transientRetries++;
+          this._logEvent('transient-retry', {
+            session_key: sessionKey,
+            chat_id: entry.chatId,
+            attempt: head.transientRetries,
+            subtype: event.subtype,
+            error: typeof errSignal === 'string' ? errSignal.slice(0, 200) : null,
+          });
+          // Reset accumulators so the retried turn's metrics aren't
+          // contaminated by the failed-turn's totals (usage on a
+          // failed turn IS billed but we surface it as a separate
+          // event-log entry rather than mixing into turn_metrics).
+          head.usageByMessage = new Map();
+          head.lastUsageMessageId = null;
+          head.toolUseCount = 0;
+          head.streamText = '';
+          head.lastAssistantMessageId = null;
+          // Re-arm idle timer (the old one is still ticking from the
+          // previous activate; resetIdleTimer just re-arms).
+          head.resetIdleTimer?.();
+          // Sleep then re-write. Keep the pending in-place; the next
+          // 'result' event resolves it normally (or hits the same
+          // retry path if MAX_TRANSIENT_RETRIES hadn't been
+          // exhausted, which after the increment above it has).
+          setTimeout(() => {
+            // Edge case: pending was killed/aborted during the
+            // retry sleep — process exited, queue drained, etc.
+            // Skip the re-write if pendingQueue no longer holds us.
+            if (entry.pendingQueue[0] !== head || entry.closed) return;
+            try {
+              entry.proc.stdin.write(JSON.stringify({
+                type: 'user',
+                message: { role: 'user', content: head.prompt },
+              }) + '\n');
+            } catch (err) {
+              // stdin write failed — fall back to surfacing the
+              // error. Mark as not-retried-anymore so we don't loop.
+              this.logger.error(`[${entry.label}] transient-retry stdin write failed: ${err.message}`);
+              entry.pendingQueue.shift();
+              head.clearTimers();
+              head.reject(err);
+            }
+          }, DEFAULT_TRANSIENT_RETRY_DELAY_MS);
+          return; // don't shift / resolve; wait for next result
+        }
+
         entry.pendingQueue.shift();
         head.clearTimers();
         if (this.onResult) this.onResult(sessionKey, event, entry, head);
@@ -546,6 +621,15 @@ class ProcessManager {
         // producing output, not when the pending becomes queue head
         // (which can be ~hundreds of ms before the first token).
         firstStreamFired: false,
+        // 0.7.7: transient-retry support. We hold the prompt so we can
+        // re-write it on transient 5xx/429 if zero assistant content
+        // streamed yet. firstAssistantSeen flips on first assistant
+        // event with non-empty content OR tool_use blocks — once true,
+        // retry is no longer idempotent (we'd replay executed tools)
+        // and pm surfaces the error instead.
+        prompt,
+        transientRetries: 0,
+        firstAssistantSeen: false,
       };
 
       pending.fireFirstStream = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "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

@@ -40,6 +40,7 @@ const { startTyping } = require('./lib/typing-indicator');
 const { redactBotToken } = require('./lib/net-errors');
 const { createReactionManager, classifyToolName } = require('./lib/status-reactions');
 const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
+const { classify: classifyError, isTransientHttpError } = require('./lib/error-classify');
 const {
   createStore: createApprovalsStore,
   matchesAnyPattern: matchesApprovalPattern,
@@ -842,30 +843,19 @@ let isShuttingDown = false;
 // killed). Anything we don't recognise falls back to a generic line
 // with a single-line snippet of the error so the user can at least
 // distinguish unique failures from the obvious "try again" cases.
+// 0.7.7: errorReplyText delegates to lib/error-classify.js so the
+// regex tables live in one place and stay in sync with future SDK
+// error subtypes (the 0.8.0 migration extends the classifier rather
+// than adding more if-branches here).
+//
+// classify() returns { kind, userMessage, isTransient, autoRecover }.
+// `userMessage: null` is a deliberate "suppress reply" signal —
+// today only used by INTERRUPTED in the abort-grace window. Callers
+// that already gate on isSessionRecentlyAborted will short-circuit
+// before reaching here, but we honour `null` defensively.
 function errorReplyText(err) {
-  const msg = err?.message || '';
-  // 0.7.6 (item H): queue overflow has a typed err.code so we don't have
-  // to grep error text. The dropped pending is OLDER than the current
-  // queue depth; its sender has likely sent more recent messages we're
-  // still working on. Tell them this one was skipped without making it
-  // sound like a crash.
-  if (err?.code === 'QUEUE_OVERFLOW') {
-    return '⏭ Couldn\'t keep up — this message was skipped while I was processing newer ones. Resend if it still matters.';
-  }
-  if (/idle with no Claude activity/i.test(msg)) {
-    return '⏳ I went quiet too long without finishing. Try resending or simplifying the task.';
-  }
-  if (/wall-clock ceiling/i.test(msg)) {
-    return '⏱ This was taking too long, so I stopped. Try resending or simplifying the task.';
-  }
-  if (/Process (exited|killed)/i.test(msg)) {
-    return '💥 Something crashed on my end. Try again.';
-  }
-  if (/error_during_execution/i.test(msg)) {
-    return '💥 Something went wrong mid-stream. Try again.';
-  }
-  const reason = msg.split('\n')[0].slice(0, 120);
-  return `Hit a snag: ${reason || 'unknown error'}. Try resending.`;
+  const { userMessage } = classifyError(err);
+  return userMessage; // may be null — caller must handle
 }
 
 // Sessions the operator just /stop'd (or natural-language "стоп"). Keyed
@@ -945,13 +935,21 @@ function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
     //    re-dispatch it on next start)
     //  - user just /stop'd (already saw their abort acknowledgement)
     if (!wasAborted && !isReplay && !isShuttingDown) {
-      tg(bot, 'sendMessage', {
-        chat_id: chatId,
-        text: errorReplyText(err),
-        reply_parameters: { message_id: msg.message_id },
-      }, { source: 'error-reply', botName: BOT_NAME }).catch((replyErr) => {
-        console.error(`[${sessionKey}] failed to send error reply: ${replyErr.message}`);
-      });
+      // 0.7.7: errorReplyText may return null when the classifier
+      // says "suppress reply" (e.g. INTERRUPTED inside abort grace —
+      // user already saw their /stop ack). Skip the send call in
+      // that case rather than dispatching empty text (which would
+      // 400 at the lib/telegram.js empty-text guard added in 0.7.4).
+      const replyText = errorReplyText(err);
+      if (replyText) {
+        tg(bot, 'sendMessage', {
+          chat_id: chatId,
+          text: replyText,
+          reply_parameters: { message_id: msg.message_id },
+        }, { source: 'error-reply', botName: BOT_NAME }).catch((replyErr) => {
+          console.error(`[${sessionKey}] failed to send error reply: ${replyErr.message}`);
+        });
+      }
     }
   }).finally(() => {
     const n = (inFlightHandlers.get(sessionKey) || 1) - 1;