@link-assistant/hive-mind 1.69.9 → 1.69.10

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @link-assistant/hive-mind
 
+## 1.69.10
+
+### Patch Changes
+
+- 7d58938: feat: add opt-in GitHub API rate-limit usage logging
+
+  Adds optional logging of current GitHub API rate-limit usage through the centralized `gh` retry wrapper so every wrapped GitHub CLI call can report quota usage while debugging.
+
+  Features:
+  - Disabled by default for backward compatibility
+  - Enable with `--github-rate-limits-logging` when debugging API usage
+  - Logs current `core`, `graphql`, and `search` rate-limit buckets after each centralized wrapped `gh` attempt
+  - Keeps the logging probe non-fatal so quota logging cannot break solve workflows
+
+  Example output:
+
+  ```
+  📊 GitHub rate limits after $gh (gh api repos): core: 780/5000 used (+29 since last check), 4220 remaining, resets 2026-05-12T10:30:00.000Z; graphql: 10/5000 used (no change), 4990 remaining, resets 2026-05-12T10:30:00.000Z
+  ```
+
 ## 1.69.9
 
 ### Patch Changes

package/CLAUDE.md

@@ -0,0 +1,5 @@
+Issue to solve: https://github.com/link-assistant/hive-mind/issues/962
+Your prepared branch: issue-962-7502f60e53a0
+Your prepared working directory: /tmp/gh-issue-solver-1766423610256
+
+Proceed.

package/package.json

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

package/src/github-rate-limit.lib.mjs

@@ -24,8 +24,16 @@ import { limitReset, retryLimits } from './config.lib.mjs';
 
 const exec = promisify(execCb);
 
+const GITHUB_RATE_LIMIT_USAGE_RESOURCES = ['core', 'graphql', 'search'];
 const RATE_LIMIT_PATTERNS = ['api rate limit exceeded', 'rate limit exceeded', 'you have exceeded a secondary rate limit', 'secondary rate limit', 'abuse detection', 'was submitted too quickly'];
 
+const githubRateLimitLogging = {
+  enabled: false,
+  log: null,
+  fetchUsage: null,
+  lastUsageByResource: null,
+};
+
 /**
  * Pull every plausible string out of a thrown error/result so pattern matches
  * survive whatever shape the upstream caller gave us (Error, exec result with
@@ -120,6 +128,116 @@ export const fetchNextRateLimitReset = async () => {
   }
 };
 
+const toFiniteNumber = value => {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+};
+
+const normalizeRateLimitUsageEntry = (resource, entry) => {
+  if (!resource || !entry) return null;
+  const limit = toFiniteNumber(entry.limit);
+  const used = toFiniteNumber(entry.used);
+  const remaining = toFiniteNumber(entry.remaining);
+  const reset = toFiniteNumber(entry.reset);
+  if (limit === null || used === null || remaining === null) return null;
+  return {
+    resource,
+    limit,
+    used,
+    remaining,
+    reset,
+    resetDate: reset === null ? null : new Date(reset * 1000),
+  };
+};
+
+/**
+ * Fetch the current GitHub API usage buckets we commonly exercise via `gh`.
+ * This intentionally calls `gh api rate_limit` directly so the logging probe
+ * does not recursively pass through the retry/logging wrapper it supports.
+ *
+ * @returns {Promise<Array<{resource: string, limit: number, used: number, remaining: number, reset: number|null, resetDate: Date|null}>>}
+ */
+export const fetchGitHubRateLimitUsage = async () => {
+  try {
+    // eslint-disable-next-line gh-rate-limit/no-direct-gh-exec -- this IS the centralized rate-limit helper; routing through itself would recurse.
+    const { stdout } = await exec('gh api rate_limit');
+    const data = JSON.parse(stdout);
+    const resources = data?.resources || {};
+    return GITHUB_RATE_LIMIT_USAGE_RESOURCES.map(resource => normalizeRateLimitUsageEntry(resource, resources[resource])).filter(Boolean);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Enable optional debug logging of actual GitHub API quota usage after each
+ * centralized `gh` wrapper attempt. Disabled by default for backward
+ * compatibility and to avoid extra `gh api rate_limit` probes in normal runs.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=false]
+ * @param {(msg: string, options?: object) => Promise<void>|void} [options.log]
+ * @param {() => Promise<Array<object>>} [options.fetchUsage] - injectable for tests.
+ */
+export const configureGitHubRateLimitLogging = ({ enabled = false, log = null, fetchUsage = null } = {}) => {
+  githubRateLimitLogging.enabled = enabled === true;
+  githubRateLimitLogging.log = typeof log === 'function' ? log : null;
+  githubRateLimitLogging.fetchUsage = typeof fetchUsage === 'function' ? fetchUsage : fetchGitHubRateLimitUsage;
+  githubRateLimitLogging.lastUsageByResource = null;
+};
+
+export const isGitHubRateLimitLoggingEnabled = () => githubRateLimitLogging.enabled;
+
+const formatUsageReset = entry => {
+  if (!(entry.resetDate instanceof Date) || Number.isNaN(entry.resetDate.getTime())) return '';
+  return `, resets ${entry.resetDate.toISOString()}`;
+};
+
+const formatRateLimitUsageEntry = entry => {
+  const previous = githubRateLimitLogging.lastUsageByResource?.[entry.resource];
+  let deltaText = '';
+  if (previous && Number.isFinite(previous.used)) {
+    const delta = entry.used - previous.used;
+    if (delta > 0) {
+      deltaText = ` (+${delta} since last check)`;
+    } else if (delta === 0) {
+      deltaText = ' (no change)';
+    } else {
+      deltaText = ' (usage reset since last check)';
+    }
+  }
+  return `${entry.resource}: ${entry.used}/${entry.limit} used${deltaText}, ${entry.remaining} remaining${formatUsageReset(entry)}`;
+};
+
+const safelyLogRateLimitUsage = async (logger, message, options) => {
+  try {
+    await Promise.resolve(logger(message, options));
+  } catch {
+    // Debug logging must never replace the original gh result or error.
+  }
+};
+
+export const logGitHubRateLimitUsage = async ({ label = 'gh' } = {}) => {
+  if (!githubRateLimitLogging.enabled) return [];
+  const logger = githubRateLimitLogging.log || (msg => console.warn(msg));
+
+  try {
+    const rawUsage = await githubRateLimitLogging.fetchUsage();
+    const usage = (Array.isArray(rawUsage) ? rawUsage : []).map(entry => normalizeRateLimitUsageEntry(entry.resource || entry.name, entry)).filter(Boolean);
+    if (usage.length === 0) return [];
+
+    const details = usage.map(formatRateLimitUsageEntry).join('; ');
+    await safelyLogRateLimitUsage(logger, `📊 GitHub rate limits after ${label}: ${details}`);
+    githubRateLimitLogging.lastUsageByResource = Object.fromEntries(usage.map(entry => [entry.resource, entry]));
+    return usage;
+  } catch (error) {
+    if (global.verboseMode) {
+      await safelyLogRateLimitUsage(logger, `⚠️ GitHub rate-limit logging failed after ${label}: ${error.message}`, { verbose: true });
+    }
+    return [];
+  }
+};
+
 /**
  * Compute the absolute wait deadline that satisfies issue #1726:
  *   reset + bufferMs (default 10 min) + random(0..jitterMs) (default 0-5 min)
@@ -226,8 +344,11 @@ export const ghWithRateLimitRetry = async (fn, options = {}) => {
 
   for (let i = 0; i < hardCap; i++) {
     try {
-      return await fn();
+      const result = await fn();
+      await logGitHubRateLimitUsage({ label });
+      return result;
     } catch (error) {
+      await logGitHubRateLimitUsage({ label });
       lastError = error;
 
       if (isRateLimitError(error)) {
@@ -324,6 +445,10 @@ export default {
   isTransientNetworkError,
   parseRateLimitReset,
   fetchNextRateLimitReset,
+  fetchGitHubRateLimitUsage,
+  configureGitHubRateLimitLogging,
+  isGitHubRateLimitLoggingEnabled,
+  logGitHubRateLimitUsage,
   computeRateLimitWait,
   ghWithRateLimitRetry,
   execGhWithRetry,

package/src/solve.config.lib.mjs

@@ -461,6 +461,11 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Include prompt to check related/sibling pull requests when studying related work. Enabled by default, use --no-prompt-check-sibling-pull-requests to disable.',
     default: true,
   },
+  'github-rate-limits-logging': {
+    type: 'boolean',
+    description: 'Log GitHub API rate-limit usage after each centralized gh command retry wrapper call. Disabled by default; use --github-rate-limits-logging to enable.',
+    default: false,
+  },
   'prompt-experiments-folder': {
     type: 'string',
     description: 'Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: ./experiments',

package/src/solve.mjs

@@ -8,7 +8,7 @@ await handleSolveEarlyExit(earlyArgs);
 const { use } = eval(await (await fetch('https://unpkg.com/use-m/use.js')).text());
 globalThis.use = use;
 const { $: __rawDollar$ } = await use('command-stream');
-const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const { configureGitHubRateLimitLogging, wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
 const $ = wrapDollarWithGhRetry(__rawDollar$);
 const config = await import('./solve.config.lib.mjs');
 const { initializeConfig, parseArguments } = config;
@@ -86,6 +86,10 @@ global.verboseMode = argv.verbose;
 
 setupVerboseLogInterceptor(); // Issue #1466: capture [VERBOSE] output in log files
 setupStdioLogInterceptor(); // Issue #1549: capture ALL terminal output in log file
+configureGitHubRateLimitLogging({
+  enabled: argv.githubRateLimitsLogging === true,
+  log,
+});
 
 // Early logs go to cwd; custom log dir takes effect after argv is parsed
 // Conditionally import tool-specific functions after argv is parsed