@link-assistant/hive-mind 1.69.15 → 1.69.17

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 1.69.17
+
+### Patch Changes
+
+- 46422f1: Increase the default `HIVE_MIND_USAGE_API_CACHE_TTL_MS` from 10 → 13 minutes so the Claude Usage API (`/api/oauth/usage`) is queried less frequently and we stop tripping the upstream "Resets in 3m Xs" rate-limit message. Operators can still override the value via the environment variable. Resolves #1798.
+
+## 1.69.16
+
+### Patch Changes
+
+- ca0d938: Fix Telegram work-session completion failing with "Bad Request: can't parse entities" when the discovered Pull request URL contained Markdown-significant characters (`_`, `*`, `` ` ``, `[`). `appendPullRequestLine` (issue #1688) inserted the raw URL into a Markdown message even though the surrounding `Issue:` line was already escaped by `buildTelegramInfoBlock`, so a repo slug like `save_visiogetbb/pull/8` opened an italic entity at byte offset 318 that never closed. The appended `Pull request:` line is now passed through `escapeMarkdown`, and `safeReply`/`safeEditMessageText`/`installTelegramFormattingFallback` now log the offending byte-offset window and the plain-text fallback under `--verbose` so future parse errors point straight to the unescaped character. Resolves #1801.
+
 ## 1.69.15
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.69.15",
+  "version": "1.69.17",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/config.lib.mjs

@@ -528,12 +528,14 @@ export const getClaudeEnv = (options = {}) => {
 // Cache TTL configurations (in milliseconds)
 // The Usage API (Claude limits) has stricter rate limiting than regular APIs
 // See: https://github.com/link-assistant/hive-mind/issues/1074
+// See: https://github.com/link-assistant/hive-mind/issues/1798
 export const cacheTtl = {
   // General API cache TTL (GitHub API, etc.)
   api: parseIntWithDefault('HIVE_MIND_API_CACHE_TTL_MS', 3 * 60 * 1000), // 3 minutes
-  // Claude Usage API cache TTL - must be at least 20 minutes to avoid rate limiting
-  // The API returns null values when called too frequently
-  usageApi: parseIntWithDefault('HIVE_MIND_USAGE_API_CACHE_TTL_MS', 10 * 60 * 1000), // 10 minutes
+  // Claude Usage API cache TTL - increased by 3 minutes (from 10 → 13) per issue #1798
+  // because users still hit "Resets in 3m xs" rate-limit responses. The API
+  // returns null values or 429 when called too frequently.
+  usageApi: parseIntWithDefault('HIVE_MIND_USAGE_API_CACHE_TTL_MS', 13 * 60 * 1000), // 13 minutes
   // System metrics cache TTL (RAM, CPU, disk)
   system: parseIntWithDefault('HIVE_MIND_SYSTEM_CACHE_TTL_MS', 2 * 60 * 1000), // 2 minutes
 };

package/src/limits.lib.mjs

@@ -1271,17 +1271,20 @@ export function formatCodexLimitsSection(codexLimits, codexError = null, options
  * Values are loaded from config.lib.mjs which supports environment variable overrides.
  *
  * IMPORTANT: The Claude Usage API has stricter rate limiting than regular APIs.
- * Calling it more frequently than every 20 minutes may result in null values being returned.
+ * Calling it too frequently may return null values or a 429 "Resets in Xm Xs" error.
+ * Default raised from 10 → 13 minutes in issue #1798 (the previous 10-minute TTL still
+ * occasionally tripped a ~3-minute rate-limit window).
  * See: https://github.com/link-assistant/hive-mind/issues/1074
+ * See: https://github.com/link-assistant/hive-mind/issues/1798
  *
  * Configurable via environment variables:
  * - HIVE_MIND_API_CACHE_TTL_MS: General API cache TTL (default: 180000 = 3 minutes)
- * - HIVE_MIND_USAGE_API_CACHE_TTL_MS: Claude Usage API cache TTL (default: 1200000 = 20 minutes)
+ * - HIVE_MIND_USAGE_API_CACHE_TTL_MS: Claude Usage API cache TTL (default: 780000 = 13 minutes)
  * - HIVE_MIND_SYSTEM_CACHE_TTL_MS: System metrics cache TTL (default: 120000 = 2 minutes)
  */
 export const CACHE_TTL = {
   API: cacheTtl.api, // 3 minutes for regular API calls (GitHub)
-  USAGE_API: cacheTtl.usageApi, // 20 minutes for Claude Usage API (rate limited)
+  USAGE_API: cacheTtl.usageApi, // 13 minutes for Claude Usage API (rate limited)
   SYSTEM: cacheTtl.system, // 2 minutes for system metrics (RAM, CPU, disk)
 };
 
@@ -1345,9 +1348,10 @@ export function resetLimitCache() {
 
 export async function getCachedClaudeLimits(verbose = false) {
   const cache = getLimitCache();
-  // Use USAGE_API TTL (20 minutes) for Claude limits to avoid rate limiting
-  // The Claude Usage API returns null values when called too frequently
+  // Use USAGE_API TTL (13 min by default, see issue #1798) for Claude limits to avoid rate limiting.
+  // The Claude Usage API returns null values or 429 errors when called too frequently.
   // See: https://github.com/link-assistant/hive-mind/issues/1074
+  // See: https://github.com/link-assistant/hive-mind/issues/1798
   const cached = cache.get('claude', CACHE_TTL.USAGE_API);
   if (cached) {
     if (verbose) console.log('[VERBOSE] /limits-cache: Using cached Claude limits (TTL: ' + Math.round(CACHE_TTL.USAGE_API / 60000) + ' minutes)');
@@ -1365,8 +1369,9 @@ export async function getCachedClaudeLimits(verbose = false) {
     cache.set('claude', result, CACHE_TTL.USAGE_API);
   } else if (result.error && result.error.includes('Rate limited')) {
     // Cache rate-limit errors to prevent hammering the API
-    // Use the same 20-minute TTL as successful responses
+    // Use the same USAGE_API TTL (13 min by default) as successful responses
     // See: https://github.com/link-assistant/hive-mind/issues/1446
+    // See: https://github.com/link-assistant/hive-mind/issues/1798
     cache.set('claude-rate-limited', result, CACHE_TTL.USAGE_API);
     if (verbose) console.log('[VERBOSE] /limits-cache: Cached rate-limit error for ' + Math.round(CACHE_TTL.USAGE_API / 60000) + ' minutes');
   }

package/src/telegram-safe-reply.lib.mjs

@@ -49,11 +49,30 @@ export function buildTelegramFormattingFallbackText(text, options = {}) {
   return `${getFormattingFallbackWarning(locale)}\n\n${stripTelegramMarkdown(text)}`;
 }
 
-function logFormattingFailure(scope, error, text, verbose = false) {
+function logFormattingFailure(scope, error, text, verbose = false, fallbackText = null) {
   const message = error?.description || error?.message || String(error || '');
   console.error(`[telegram-bot] ${scope}: formatted Telegram message failed: ${message}`);
   if (verbose) {
-    console.error(`[telegram-bot] ${scope}: Failing message (${Buffer.byteLength(String(text ?? ''), 'utf-8')} bytes): ${text}`);
+    const originalBytes = Buffer.byteLength(String(text ?? ''), 'utf-8');
+    console.error(`[telegram-bot] ${scope}: Failing message (${originalBytes} bytes): ${text}`);
+    // Issue #1801: when the parser rejects an entity, surface the byte offset
+    //   from the error along with a small window of the message around it to
+    //   make pinpointing the offending character trivial on the next iteration.
+    const offsetMatch = /byte offset (\d+)/i.exec(message);
+    if (offsetMatch) {
+      const offset = Number(offsetMatch[1]);
+      const buf = Buffer.from(String(text ?? ''), 'utf-8');
+      const start = Math.max(0, offset - 32);
+      const end = Math.min(buf.length, offset + 32);
+      // Decode the window; replacement character is used for bytes that fall
+      // mid-codepoint so we still print *something* useful.
+      const window = buf.slice(start, end).toString('utf-8');
+      console.error(`[telegram-bot] ${scope}: Byte offset ${offset} context [${start}..${end}]: ${JSON.stringify(window)}`);
+    }
+    if (fallbackText !== null) {
+      const fallbackBytes = Buffer.byteLength(String(fallbackText ?? ''), 'utf-8');
+      console.error(`[telegram-bot] ${scope}: Fallback message (${fallbackBytes} bytes): ${fallbackText}`);
+    }
   }
 }
 
@@ -65,8 +84,8 @@ export async function safeReply(ctx, text, options = {}) {
     return await ctx.reply(text, firstOptions);
   } catch (error) {
     if (!isTelegramFormattingError(error)) throw error;
-    logFormattingFailure('safeReply', error, text, verbose);
     const fallbackText = buildTelegramFormattingFallbackText(text, { fallbackLocale });
+    logFormattingFailure('safeReply', error, text, verbose, fallbackText);
     return await ctx.reply(fallbackText, { ...telegramOptions, parse_mode: undefined });
   }
 }
@@ -78,8 +97,8 @@ export async function safeEditMessageText(telegram, chatId, messageId, inlineMes
     return await telegram.editMessageText(chatId, messageId, inlineMessageId, text, firstOptions);
   } catch (error) {
     if (!isTelegramFormattingError(error)) throw error;
-    logFormattingFailure('safeEditMessageText', error, text, verbose);
     const fallbackText = buildTelegramFormattingFallbackText(text, { fallbackLocale });
+    logFormattingFailure('safeEditMessageText', error, text, verbose, fallbackText);
     return await telegram.editMessageText(chatId, messageId, inlineMessageId, fallbackText, { ...telegramOptions, parse_mode: undefined });
   }
 }
@@ -98,9 +117,10 @@ function wrapTelegramMethod(telegram, methodName, textIndex, optionsIndex, defau
       return await original.apply(this, args);
     } catch (error) {
       if (!isTelegramFormattingError(error) || typeof text !== 'string') throw error;
-      logFormattingFailure(methodName, error, text, verbose || defaults.verbose);
+      const fallbackText = buildTelegramFormattingFallbackText(text, { fallbackLocale: fallbackLocale || defaults.fallbackLocale });
+      logFormattingFailure(methodName, error, text, verbose || defaults.verbose, fallbackText);
       const retryArgs = [...args];
-      retryArgs[textIndex] = buildTelegramFormattingFallbackText(text, { fallbackLocale: fallbackLocale || defaults.fallbackLocale });
+      retryArgs[textIndex] = fallbackText;
       retryArgs[optionsIndex] = { ...telegramOptions, parse_mode: undefined };
       return await original.apply(this, retryArgs);
     }

package/src/telegram-show-limits.lib.mjs

@@ -5,8 +5,8 @@
  * the args before they are forwarded to /solve, /hive (or /task --split). When
  * set, the bot:
  *   1. Fetches usage limits for the selected tool (Claude or Codex) using the
- *      shared cached helpers in limits.lib.mjs (TTL: 20 minutes for the usage
- *      API to avoid rate limiting).
+ *      shared cached helpers in limits.lib.mjs (USAGE_API TTL: 13 minutes by
+ *      default — see issue #1798 — to avoid rate limiting).
  *   2. Embeds a compact "Limits at start" snapshot below the infoBlock so the
  *      starting/executing message shows the user how much budget they had at
  *      the moment the command was queued.

package/src/work-session-formatting.lib.mjs

@@ -1,4 +1,5 @@
 import { t } from './i18n.lib.mjs';
+import { escapeMarkdown } from './telegram-markdown.lib.mjs';
 
 const FAILURE_STATUSES = new Set(['failed', 'cancelled', 'canceled', 'error']);
 
@@ -74,7 +75,7 @@ export function formatExecutingWorkSessionMessage({ sessionName = 'unknown', iso
  */
 export function appendPullRequestLine(infoBlock, pullRequestUrl, { locale = null } = {}) {
   if (!pullRequestUrl || !infoBlock) return infoBlock || '';
-  if (infoBlock.includes(pullRequestUrl)) return infoBlock;
+  if (infoBlock.includes(pullRequestUrl) || infoBlock.includes(escapeMarkdown(pullRequestUrl))) return infoBlock;
 
   const lines = infoBlock.split('\n');
   let lastUrlLineIdx = -1;
@@ -89,7 +90,10 @@ export function appendPullRequestLine(infoBlock, pullRequestUrl, { locale = null
       lastUrlLineIdx = i;
     }
   }
-  const prLine = `${text(locale, 'telegram.info_pull_request_label', 'Pull request')}: ${pullRequestUrl}`;
+  // Issue #1801: escape underscores/asterisks so Markdown parser doesn't open
+  //   an entity on URLs like .../save_visiogetbb/pull/8 that the Issue: line
+  //   above already had escaped at buildTelegramInfoBlock time.
+  const prLine = `${text(locale, 'telegram.info_pull_request_label', 'Pull request')}: ${escapeMarkdown(pullRequestUrl)}`;
   if (lastUrlLineIdx === -1) {
     return `${infoBlock}\n${prLine}`;
   }