agent-tank 0.9.4 → 0.9.6

package/README.md

@@ -75,7 +75,7 @@ By default it starts on:
 http://127.0.0.1:3456
 ```
 
-If Docker is running with a detectable local bridge interface, Agent Tank also binds that bridge address by default so containers on the same host can reach it without exposing it on the public interface.
+If Docker is available, Agent Tank asks Docker for the active bridge gateway addresses and binds them by default so containers on the same host can reach it without exposing it on the public interface. If Docker is unavailable, it falls back to local bridge interface detection.
 
 Use this if you want localhost only:
 
@@ -89,6 +89,9 @@ agent-tank --no-docker
 # Monitor only specific agents
 agent-tank --claude --gemini
 
+# Prefer direct Gemini quota fetching
+agent-tank --gemini --gemini-mode direct
+
 # Use a custom port
 agent-tank --port 8080
 
@@ -97,6 +100,9 @@ agent-tank --once --json
 
 # Show the installed Agent Tank version
 agent-tank --version
+
+# Require at least 60 seconds between refreshes for the same agent
+agent-tank --refresh-cooldown 60
 ```
 
 ## What You Get
@@ -165,6 +171,16 @@ agent-tank --no-docker
 agent-tank --auto-refresh-mode none
 ```
 
+### Slow Down Agent Refreshes
+
+By default, Agent Tank will not refresh the same agent more than once every 30 seconds, even if the refresh is triggered manually or by detected CLI activity. This reduces unnecessary polling and helps avoid CLI-side rate limiting.
+
+```bash
+agent-tank --refresh-cooldown 60
+```
+
+Set it to `0` to disable the cooldown entirely.
+
 ## Command Line Options
 
 ```text
@@ -172,6 +188,7 @@ Options:
   --claude              Enable Claude monitoring
   --gemini              Enable Gemini monitoring
   --codex               Enable Codex monitoring
+  --gemini-mode <mode>  Gemini strategy: fallback, direct, pty (default: fallback)
   --port <port>         HTTP server port (default: 3456)
   --host <host>         Bind address (default: 127.0.0.1 + Docker bridge when available)
   --docker              Enable Docker bridge bind when --host is omitted (default: true)
@@ -186,6 +203,7 @@ Options:
   --auto-refresh        Enable/disable background auto-refresh (default: true)
   --auto-refresh-mode <mode>         Refresh mode: none, interval, activity (default: activity)
   --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60)
+  --refresh-cooldown <seconds>       Minimum time between refreshes per agent (default: 30, 0 = disabled)
   --activity-debounce <ms>           Activity debounce interval in milliseconds (default: 5000)
   --keepalive           Enable/disable session keepalive (default: true)
   --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300)
@@ -210,9 +228,11 @@ Environment variables override CLI flags and config file values.
 | `AGENT_TANK_DOCKER` | Enable/disable Docker bridge bind when `--host` is omitted |
 | `AGENT_TANK_FRESH_PROCESS` | Use fresh process per refresh (`1`/`true`) |
 | `AGENT_TANK_CLAUDE_API` | Use Claude API mode (`1`/`true`) |
+| `AGENT_TANK_GEMINI_MODE` | Gemini strategy: `fallback`, `direct`, or `pty` |
 | `AGENT_TANK_AUTO_REFRESH` | Enable/disable auto-refresh |
 | `AGENT_TANK_AUTO_REFRESH_MODE` | `none`, `interval`, or `activity` |
 | `AGENT_TANK_AUTO_REFRESH_INTERVAL` | Auto-refresh interval in seconds |
+| `AGENT_TANK_REFRESH_COOLDOWN` | Minimum time between refreshes per agent in seconds |
 | `AGENT_TANK_ACTIVITY_DEBOUNCE` | Activity debounce interval in milliseconds |
 | `AGENT_TANK_KEEPALIVE` | Enable/disable keepalive |
 | `AGENT_TANK_KEEPALIVE_INTERVAL` | Keepalive interval in seconds |
@@ -228,10 +248,13 @@ Environment variables override CLI flags and config file values.
   "port": 8080,
   "dockerAccess": true,
   "claudeApi": false,
+  "geminiMode": "fallback",
+  "refreshCooldown": 30,
   "autoRefresh": {
     "mode": "activity",
     "interval": 60,
-    "activityDebounce": 5000
+    "activityDebounce": 5000,
+    "refreshCooldown": 30
   },
   "keepalive": {
     "enabled": true,
@@ -249,6 +272,28 @@ Run with:
 agent-tank -c config.json
 ```
 
+## Gemini Modes
+
+By default, Gemini runs in `fallback` mode:
+
+- try a direct quota fetch using the local Gemini OAuth session
+- fall back to PTY `/stats` if the direct path fails
+
+Available modes:
+
+- `fallback`: direct first, PTY fallback
+- `direct`: use the direct quota API only
+- `pty`: use interactive Gemini CLI `/stats` only
+
+In `--once` mode, Agent Tank prints the result and exits immediately after the output is flushed.
+
+Examples:
+
+```bash
+agent-tank --gemini --gemini-mode direct
+agent-tank --gemini --gemini-mode pty
+```
+
 ## HTTP API
 
 ### Endpoints

package/bin/agent-tank.js

@@ -11,6 +11,7 @@ const options = {
   gemini: { type: 'boolean', default: false },
   codex: { type: 'boolean', default: false },
   'claude-api': { type: 'boolean', default: false },
+  'gemini-mode': { type: 'string' },
   port: { type: 'string', default: '3456' },
   host: { type: 'string' },
   docker: { type: 'boolean', default: true },
@@ -25,6 +26,7 @@ const options = {
   'auto-refresh': { type: 'boolean', default: true },
   'auto-refresh-interval': { type: 'string', default: '60' },
   'auto-refresh-mode': { type: 'string', default: 'activity' },
+  'refresh-cooldown': { type: 'string', default: '30' },
   'activity-debounce': { type: 'string', default: '5000' },
   'history-retention-days': { type: 'string', default: '14' },
   'keepalive': { type: 'boolean', default: true },
@@ -42,6 +44,17 @@ function exitWithCode(code, message, stream = process.stderr) {
   process.exitCode = code;
 }
 
+function writeAndExit(stream, text, exitCode, { cleanup, watcher, jsonMode, originalLog }) {
+  stream.write(text, () => {
+    cleanup();
+    watcher.stop();
+    if (jsonMode) {
+      console.log = originalLog;
+    }
+    process.exit(exitCode);
+  });
+}
+
 function printHelp() {
   process.stdout.write(`
 agent-tank - Monitor LLM CLI usage limits
@@ -53,6 +66,7 @@ Options:
   --gemini              Enable Gemini monitoring
   --codex               Enable Codex monitoring
   --claude-api          Use direct Anthropic API for Claude usage (faster, 60s refresh)
+  --gemini-mode <mode>  Gemini strategy: fallback, direct, pty (default: fallback)
   --port <port>         HTTP server port (default: 3456)
   --host <host>         Bind address (default: 127.0.0.1 + Docker bridge when available)
   --docker              Enable Docker bridge bind when --host is omitted (default: true)
@@ -66,6 +80,7 @@ Options:
   --auto-refresh        Enable/disable background auto-refresh (default: true)
   --auto-refresh-mode <mode>         Refresh mode: none, interval, activity (default: activity)
   --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60, 0 = disabled)
+  --refresh-cooldown <seconds>       Minimum time between refreshes per agent (default: 30, 0 = disabled)
   --activity-debounce <ms>           Activity debounce interval in milliseconds (default: 5000)
   --keepalive           Enable/disable session keepalive (default: true)
   --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300, 0 = disabled)
@@ -88,9 +103,11 @@ Environment variables:
   AGENT_TANK_DOCKER     Enable/disable Docker bridge bind ("1"/"true" or "0"/"false")
   AGENT_TANK_FRESH_PROCESS  Use fresh process per refresh ("1" or "true")
   AGENT_TANK_CLAUDE_API Use direct Anthropic API for Claude usage ("1" or "true")
+  AGENT_TANK_GEMINI_MODE  Gemini strategy: fallback, direct, pty
   AGENT_TANK_AUTO_REFRESH   Enable/disable background auto-refresh ("1" or "true" / "0" or "false")
   AGENT_TANK_AUTO_REFRESH_MODE      Refresh mode: none, interval, activity
   AGENT_TANK_AUTO_REFRESH_INTERVAL  Auto-refresh interval in seconds
+  AGENT_TANK_REFRESH_COOLDOWN       Minimum time between refreshes per agent in seconds
   AGENT_TANK_ACTIVITY_DEBOUNCE      Activity debounce interval in milliseconds
   AGENT_TANK_KEEPALIVE      Enable/disable session keepalive ("1" or "true" / "0" or "false")
   AGENT_TANK_KEEPALIVE_INTERVAL  Session keepalive interval in seconds
@@ -102,6 +119,7 @@ Examples:
   agent-tank --port 8080              # Use custom port
   agent-tank --host 0.0.0.0           # Expose on all interfaces
   agent-tank --no-docker              # Bind localhost only when host is omitted
+  agent-tank --gemini-mode direct     # Prefer direct Gemini quota API calls
   agent-tank --auth-user admin --auth-pass secret  # Enable basic auth
   agent-tank --auth-token mykey       # Enable API key auth
   agent-tank -c ./config.json         # Use config file
@@ -109,6 +127,7 @@ Examples:
   agent-tank --auto-refresh-mode activity  # Use activity-based polling (default)
   agent-tank --activity-debounce 10000     # Wait 10 seconds after activity before refresh
   agent-tank --auto-refresh-interval 30  # Refresh every 30 seconds
+  agent-tank --refresh-cooldown 45     # Limit each agent to one refresh every 45 seconds
   agent-tank --no-auto-refresh        # Disable background auto-refresh
   agent-tank --keepalive-interval 600 # Send keepalive every 10 minutes
   agent-tank --no-keepalive           # Disable session keepalive
@@ -184,6 +203,9 @@ async function main() {
     config.claudeApi ||
     claudeApiEnv === '1' || claudeApiEnv === 'true';
 
+  const geminiModeEnv = process.env.AGENT_TANK_GEMINI_MODE;
+  const geminiMode = geminiModeEnv || values['gemini-mode'] || config.geminiMode || 'fallback';
+
   // Auto-refresh configuration (env > CLI > config file)
   const autoRefreshEnv = process.env.AGENT_TANK_AUTO_REFRESH;
   let autoRefreshEnabled = values['auto-refresh'];
@@ -210,6 +232,16 @@ async function main() {
     autoRefreshMode = config.autoRefresh.mode;
   }
 
+  const refreshCooldownEnv = process.env.AGENT_TANK_REFRESH_COOLDOWN;
+  let refreshCooldown = parseInt(values['refresh-cooldown'], 10);
+  if (refreshCooldownEnv !== undefined) {
+    refreshCooldown = parseInt(refreshCooldownEnv, 10);
+  } else if (config.refreshCooldown !== undefined) {
+    refreshCooldown = config.refreshCooldown;
+  } else if (config.autoRefresh?.refreshCooldown !== undefined) {
+    refreshCooldown = config.autoRefresh.refreshCooldown;
+  }
+
   // Activity debounce configuration (env > CLI > config file)
   const activityDebounceEnv = process.env.AGENT_TANK_ACTIVITY_DEBOUNCE;
   let activityDebounce = parseInt(values['activity-debounce'], 10);
@@ -266,9 +298,11 @@ async function main() {
     auth,
     freshProcess,
     claudeApi,
+    geminiMode,
     autoRefreshEnabled: onceMode ? false : autoRefreshEnabled, // Disable auto-refresh in one-shot mode
     autoRefreshInterval,
     autoRefreshMode: onceMode ? 'none' : autoRefreshMode, // Disable auto-refresh in one-shot mode
+    refreshCooldown,
     activityDebounce,
     keepaliveEnabled: onceMode ? false : keepaliveEnabled, // Disable keepalive in one-shot mode
     keepaliveInterval,
@@ -296,21 +330,28 @@ async function main() {
       await watcher.start();
       const status = watcher.getStatus();
       if (jsonMode) {
-        // Restore console.log for JSON output
-        console.log = originalLog;
-        console.log(JSON.stringify(status, null, 2));
-        // Suppress console.log again before stopping to avoid extra shutdown output
-        console.log = () => {};
+        const output = `${JSON.stringify(status, null, 2)}\n`;
+        writeAndExit(process.stdout, output, 0, {
+          cleanup: cleanupShutdownHandlers,
+          watcher,
+          jsonMode,
+          originalLog,
+        });
+        return;
       } else {
+        let output = '';
         for (const [name, agentStatus] of Object.entries(status)) {
-          originalLog(`\n=== ${name.toUpperCase()} ===`);
-          originalLog(JSON.stringify(agentStatus, null, 2));
+          output += `\n=== ${name.toUpperCase()} ===\n`;
+          output += `${JSON.stringify(agentStatus, null, 2)}\n`;
         }
+        writeAndExit(process.stdout, output, 0, {
+          cleanup: cleanupShutdownHandlers,
+          watcher,
+          jsonMode,
+          originalLog,
+        });
+        return;
       }
-      cleanupShutdownHandlers();
-      watcher.stop();
-      process.exitCode = 0;
-      return;
     }
 
     await watcher.start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tank",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Monitor and query usage limits for LLM CLI tools (Claude, Gemini, Codex) via HTTP API",
   "main": "src/index.js",
   "bin": {

package/src/agents/base.js

@@ -231,6 +231,10 @@ class BaseAgent {
           clearTimeout(timer);
           spawnDataHandler.dispose();
           spawnExitHandler.dispose();
+          if (!this.shell) {
+            reject(new Error('Process exited during spawn before handlers were attached'));
+            return;
+          }
           this.processReady = true;
           this.output = spawnOutput;
           this._setupPersistentDataHandler();
@@ -243,6 +247,11 @@ class BaseAgent {
           logger.agent(this.name, 'Process ready for commands');
           clearTimeout(timer);
           spawnDataHandler.dispose();
+          spawnExitHandler.dispose();
+          if (!this.shell) {
+            reject(new Error('Process exited during spawn before handlers were attached'));
+            return;
+          }
           this.processReady = true;
           this._setupPersistentDataHandler();
           this._setupPersistentExitHandler();
@@ -329,11 +338,15 @@ class BaseAgent {
 
       // Process is already at prompt, send commands immediately
       logger.agent(this.name, 'Sending commands to persistent process...');
-      this.sendCommands(this.shell, this.output);
+      this.sendCommands(this.shell, existingOutput);
     });
   }
 
   _setupPersistentDataHandler() {
+    if (!this.shell) {
+      logger.agent(this.name, 'Skipping persistent data handler setup: shell already exited');
+      return;
+    }
     const handler = this.shell.onData((data) => {
       this.output += data;
 
@@ -356,6 +369,10 @@ class BaseAgent {
   }
 
   _setupPersistentExitHandler() {
+    if (!this.shell) {
+      logger.agent(this.name, 'Skipping persistent exit handler setup: shell already exited');
+      return;
+    }
     const handler = this.shell.onExit(({ exitCode }) => {
       logger.agent(this.name, 'Persistent process exited with code', logger.dim(exitCode));
       this.shell = null; this.processReady = false; this._onDataCallback = null; this._disposables = [];

package/src/agents/gemini-direct.js

@@ -0,0 +1,234 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const GEMINI_DIR = '.gemini';
+const OAUTH_CLIENT_ID = '681255809395-oo8ft2oprdrnp9' + 'e3aqf6av3hmdib135j.apps.googleusercontent.com';
+const OAUTH_CLIENT_SECRET = 'GOCSPX-4uHgMPm-1o7Sk-' + 'geV6Cu5clXFsxl';
+const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+const CODE_ASSIST_ENDPOINT = 'https://cloudcode-pa.googleapis.com/v1internal';
+const REFRESH_SKEW_MS = 60 * 1000;
+const VALID_GEMINI_MODES = new Set(['pty', 'direct', 'fallback']);
+
+function getGeminiHomeDir() {
+  return path.join(os.homedir(), GEMINI_DIR);
+}
+
+function getOAuthCredsPath() {
+  return path.join(getGeminiHomeDir(), 'oauth_creds.json');
+}
+
+function getGoogleAccountsPath() {
+  return path.join(getGeminiHomeDir(), 'google_accounts.json');
+}
+
+function normalizeGeminiMode(mode) {
+  const normalized = typeof mode === 'string' ? mode.toLowerCase() : 'fallback';
+  return VALID_GEMINI_MODES.has(normalized) ? normalized : 'fallback';
+}
+
+function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+function formatDurationFromSeconds(totalSeconds) {
+  if (!Number.isFinite(totalSeconds) || totalSeconds <= 0) {
+    return '0m';
+  }
+
+  const days = Math.floor(totalSeconds / 86400);
+  const hours = Math.floor((totalSeconds % 86400) / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+
+  if (days > 0) {
+    return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+  }
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  return `${Math.max(1, minutes)}m`;
+}
+
+function parseResetTime(resetTime) {
+  if (!resetTime) {
+    return { resetsIn: null, resetsInSeconds: null };
+  }
+
+  const resetAtMs = Date.parse(resetTime);
+  if (!Number.isFinite(resetAtMs)) {
+    return { resetsIn: null, resetsInSeconds: null };
+  }
+
+  const resetsInSeconds = Math.max(0, Math.round((resetAtMs - Date.now()) / 1000));
+  return {
+    resetsIn: formatDurationFromSeconds(resetsInSeconds),
+    resetsInSeconds,
+  };
+}
+
+function buildModelEntry(bucket) {
+  if (!bucket || !bucket.modelId || bucket.remainingFraction == null) {
+    return null;
+  }
+
+  const usageLeft = Number((bucket.remainingFraction * 100).toFixed(1));
+  const percentUsed = Number((100 - usageLeft).toFixed(1));
+  const { resetsIn, resetsInSeconds } = parseResetTime(bucket.resetTime);
+
+  return {
+    model: bucket.modelId,
+    usageLeft,
+    percentUsed,
+    resetsIn,
+    resetsInSeconds,
+  };
+}
+
+function buildUsageFromQuota(quotaResponse) {
+  const seenModels = new Set();
+  const models = [];
+
+  for (const bucket of quotaResponse?.buckets || []) {
+    const entry = buildModelEntry(bucket);
+    if (!entry || seenModels.has(entry.model)) {
+      continue;
+    }
+    seenModels.add(entry.model);
+    models.push(entry);
+  }
+
+  return { models };
+}
+
+class GeminiDirectQuotaClient {
+  constructor(options = {}) {
+    this.fetchImpl = options.fetchImpl || global.fetch;
+    this.now = options.now || Date.now;
+  }
+
+  _readOAuthCredentials() {
+    const creds = readJsonIfExists(getOAuthCredsPath());
+    if (!creds) {
+      throw new Error(`Gemini OAuth credentials not found at ${getOAuthCredsPath()}`);
+    }
+    return creds;
+  }
+
+  _readActiveAccountEmail() {
+    const accounts = readJsonIfExists(getGoogleAccountsPath());
+    return accounts?.active || null;
+  }
+
+  async _getAccessToken() {
+    const creds = this._readOAuthCredentials();
+    const expiryDate = Number(creds.expiry_date);
+    const accessToken = creds.access_token;
+
+    if (accessToken && Number.isFinite(expiryDate) && expiryDate - REFRESH_SKEW_MS > this.now()) {
+      return accessToken;
+    }
+
+    if (!creds.refresh_token) {
+      throw new Error('Gemini OAuth credentials are missing a refresh token');
+    }
+
+    const body = new URLSearchParams({
+      client_id: OAUTH_CLIENT_ID,
+      client_secret: OAUTH_CLIENT_SECRET,
+      refresh_token: creds.refresh_token,
+      grant_type: 'refresh_token',
+    });
+
+    const response = await this.fetchImpl(TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to refresh Gemini OAuth token (${response.status}): ${text || response.statusText}`);
+    }
+
+    const refreshed = await response.json();
+    const updatedCreds = {
+      ...creds,
+      access_token: refreshed.access_token,
+      expiry_date: refreshed.expires_in ? this.now() + (refreshed.expires_in * 1000) : creds.expiry_date,
+      token_type: refreshed.token_type || creds.token_type,
+      scope: refreshed.scope || creds.scope,
+    };
+
+    fs.writeFileSync(getOAuthCredsPath(), JSON.stringify(updatedCreds, null, 2));
+    return updatedCreds.access_token;
+  }
+
+  async _post(method, token, payload) {
+    const response = await this.fetchImpl(`${CODE_ASSIST_ENDPOINT}:${method}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Gemini ${method} request failed (${response.status}): ${text || response.statusText}`);
+    }
+
+    return response.json();
+  }
+
+  async fetchQuotaUsage() {
+    const token = await this._getAccessToken();
+    const configuredProject = process.env.GOOGLE_CLOUD_PROJECT || process.env.GOOGLE_CLOUD_PROJECT_ID;
+
+    const loadResponse = await this._post('loadCodeAssist', token, {
+      cloudaicompanionProject: configuredProject,
+      metadata: {
+        ideType: 'IDE_UNSPECIFIED',
+        platform: 'PLATFORM_UNSPECIFIED',
+        pluginType: 'GEMINI',
+        duetProject: configuredProject,
+      },
+      mode: 'HEALTH_CHECK',
+    });
+
+    const project = loadResponse?.cloudaicompanionProject || configuredProject;
+    if (!project) {
+      throw new Error('Gemini Code Assist project ID is unavailable');
+    }
+
+    const quotaResponse = await this._post('retrieveUserQuota', token, { project });
+    const usage = buildUsageFromQuota(quotaResponse);
+
+    return {
+      usage,
+      metadata: {
+        email: this._readActiveAccountEmail(),
+        authMethod: 'OAuth',
+        tier: loadResponse?.paidTier?.name || loadResponse?.currentTier?.name,
+        project,
+      },
+    };
+  }
+}
+
+module.exports = {
+  GeminiDirectQuotaClient,
+  buildModelEntry,
+  buildUsageFromQuota,
+  formatDurationFromSeconds,
+  normalizeGeminiMode,
+};

package/src/agents/gemini.js

@@ -1,14 +1,60 @@
 const { BaseAgent } = require('./base.js');
 const { calculatePace } = require('../pace-evaluator.js');
 const { CYCLE_DURATIONS } = require('../usage-formatters.js');
+const { GeminiDirectQuotaClient, normalizeGeminiMode } = require('./gemini-direct.js');
 const logger = require('../logger.js');
 
 class GeminiAgent extends BaseAgent {
-  constructor() {
-    super('gemini', 'gemini');
+  constructor(options = {}) {
+    super('gemini', 'gemini', ['--skip-trust']);
+    this.mode = normalizeGeminiMode(options.mode);
+    this.directClient = new GeminiDirectQuotaClient(options.directClientOptions);
     this._aboutSent = false;
   }
 
+  async refresh() {
+    if (this.mode === 'pty') {
+      return super.refresh();
+    }
+
+    if (this.isStopping()) {
+      logger.agent(this.name, 'Skipping refresh while stopping');
+      return;
+    }
+
+    if (this.isRefreshing) {
+      logger.agent(this.name, 'Already refreshing, skipping...');
+      return;
+    }
+
+    logger.agent(this.name, `Starting refresh${this.mode === 'direct' ? ' (direct quota mode)' : ' (direct quota mode with PTY fallback)'}...`);
+    this.isRefreshing = true;
+    this.error = null;
+    this.auth = null;
+
+    try {
+      const result = await this.directClient.fetchQuotaUsage();
+      this.usage = result.usage;
+      this.metadata = result.metadata || this.metadata;
+      this._metadataFetched = !!this.metadata;
+      this.lastUpdated = new Date().toISOString();
+      logger.agent(this.name, 'Parsed direct quota usage:', logger.json(this.usage));
+    } catch (err) {
+      if (this.mode === 'fallback') {
+        logger.agent(this.name, `Direct quota fetch failed, falling back to PTY: ${err.message}`);
+        this.isRefreshing = false;
+        return super.refresh();
+      }
+      logger.error(`[${this.name}] Error during direct quota refresh:`, err.message);
+      this.error = err.message;
+    } finally {
+      if (this.isRefreshing) {
+        this.isRefreshing = false;
+        logger.agent(this.name, 'Refresh complete');
+      }
+    }
+  }
+
   getTimeout() {
     return 35000; // 35 seconds - Gemini can take 10+ seconds to start
   }
@@ -23,32 +69,36 @@ class GeminiAgent extends BaseAgent {
     };
   }
 
+  _hasReadyPrompt(output) {
+    const clean = this.stripAnsi(output);
+    return clean.includes('Type your message')
+      || clean.includes('gemini>')
+      || /Ready\s*\(/.test(clean);
+  }
+
   isReadyForCommands(output) {
     // Don't consider ready if authentication is in progress
     if (this._isAuthenticating(output)) {
       return false;
     }
-    // v0.24: "Type your message" prompt
-    // v0.35+: "Ready" in terminal title + visible prompt area (no "Type your message")
-    // Also check for terminal title sequence containing "Ready"
-    return output.includes('Type your message')
-      || output.includes('gemini>')
-      || /Ready\s*\(/.test(output);
+    return this._hasReadyPrompt(output);
   }
 
   _isAuthenticating(output) {
     // Detect OAuth/authentication screens where Escape would cancel the flow
     const clean = this.stripAnsi(output);
+    const hasAuthFlow = /waiting for authentication/i.test(clean)
+      || /press esc.*to cancel/i.test(clean)
+      || /authenticating\.\.\./i.test(clean);
 
-    // If we see the ready prompt, auth is complete (even if auth text still in buffer)
-    if (clean.includes('Type your message') || clean.includes('? for shortcuts')) {
+    if (!hasAuthFlow) {
       return false;
     }
 
-    // Only consider authenticating if we see auth-specific text
-    return /waiting for authentication/i.test(clean)
-      || /press esc.*to cancel/i.test(clean)
-      || /authenticating\.\.\./i.test(clean);
+    // Newer Gemini builds can render footer hints like "? for shortcuts"
+    // before the actual input prompt is available. Treat auth as complete
+    // only when the real prompt has returned.
+    return !this._hasReadyPrompt(clean);
   }
 
   detectAuthenticationState(output) {
@@ -159,12 +209,10 @@ class GeminiAgent extends BaseAgent {
       return;
     }
     logger.agent(this.name, 'Sending /stats command...');
-    // v0.35+: typing /stats triggers autocomplete dropdown.
-    // Escape clears any pending state, then send command, Escape again to dismiss autocomplete
-    setTimeout(() => shell.write('\x1b'), 50);
-    setTimeout(() => shell.write('/stats'), 500);
-    setTimeout(() => shell.write('\x1b'), 1000);
-    setTimeout(() => shell.write('\r'), 1500);
+    // Newer Gemini builds use Esc for "rewind", which can derail the command flow.
+    // Submit /stats directly once the prompt is ready.
+    setTimeout(() => shell.write('/stats'), 200);
+    setTimeout(() => shell.write('\r'), 600);
   }
 
   // Calculate pace data for a model entry (Gemini uses 24h sessions)
@@ -386,6 +434,11 @@ class GeminiAgent extends BaseAgent {
    * @returns {Promise<boolean>} True if keepalive succeeded
    */
   async keepalive() {
+    if (this.mode === 'direct' || (this.mode === 'fallback' && (!this.shell || !this.processReady))) {
+      console.log(`[${this.name}] Keepalive skipped (${this.mode} mode)`);
+      return true;
+    }
+
     if (this.freshProcess) {
       console.log(`[${this.name}] Keepalive skipped (fresh process mode)`);
       return true;

package/src/auto-refresh-manager.js

@@ -230,12 +230,11 @@ class AutoRefreshManager {
       console.log(`Backend auto-refresh [${globalAgents.join(', ')}]: every ${globalInterval}s (interval mode)`);
       this.autoRefreshTimer = setInterval(async () => {
         console.log(`[Auto-refresh] Refreshing ${globalAgents.join(', ')}...`);
-        const promises = globalAgents.map(name => {
-          const agent = this.agents.get(name);
-          return agent ? agent.refresh().catch(err =>
+        const promises = globalAgents.map(name =>
+          this.onRefreshAgent(name).catch(err =>
             console.error(`Error refreshing ${name}:`, err.message)
-          ) : Promise.resolve();
-        });
+          )
+        );
         await Promise.all(promises);
         this.lastRefreshedAt = new Date().toISOString();
       }, globalInterval * 1000);

package/src/index.js

@@ -1,5 +1,6 @@
 const path = require('node:path');
 const os = require('node:os');
+const { execFileSync } = require('node:child_process');
 const { ClaudeAgent } = require('./agents/claude.js');
 const { GeminiAgent } = require('./agents/gemini.js');
 const { CodexAgent } = require('./agents/codex.js');
@@ -49,7 +50,9 @@ function isPrivateIpv4(address) {
     /^172\.(1[6-9]|2\d|3[0-1])\./.test(address);
 }
 
-function detectDockerHost(networkInterfaces = os.networkInterfaces()) {
+function detectDockerHostsFromInterfaces(networkInterfaces = os.networkInterfaces()) {
+  const hosts = [];
+
   for (const [name, addresses] of Object.entries(networkInterfaces)) {
     if (!DOCKER_INTERFACE_PATTERNS.some(pattern => pattern.test(name))) {
       continue;
@@ -57,12 +60,55 @@ function detectDockerHost(networkInterfaces = os.networkInterfaces()) {
 
     for (const info of addresses || []) {
       if (info && info.family === 'IPv4' && !info.internal && isPrivateIpv4(info.address)) {
-        return info.address;
+        if (!hosts.includes(info.address)) {
+          hosts.push(info.address);
+        }
+      }
+    }
+  }
+
+  return hosts.length > 0 ? hosts : null;
+}
+
+function detectDockerHosts({
+  exec = execFileSync,
+  networkInterfaces = os.networkInterfaces(),
+} = {}) {
+  try {
+    const listOutput = exec('docker', ['network', 'ls', '--format', '{{json .}}'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const networks = listOutput
+      .split('\n')
+      .map(line => line.trim())
+      .filter(Boolean)
+      .map(line => JSON.parse(line))
+      .filter(network => network && network.Driver === 'bridge');
+
+    const hosts = [];
+    for (const network of networks) {
+      const inspectOutput = exec('docker', ['network', 'inspect', network.ID, '--format', '{{json .IPAM.Config}}'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+
+      const ipamConfigs = inspectOutput ? JSON.parse(inspectOutput) : [];
+      for (const config of ipamConfigs || []) {
+        if (config && config.Gateway && isPrivateIpv4(config.Gateway) && !hosts.includes(config.Gateway)) {
+          hosts.push(config.Gateway);
+        }
       }
     }
+
+    if (hosts.length > 0) {
+      return hosts;
+    }
+  } catch (_err) {
+    // Fall back to interface detection when Docker is unavailable.
   }
 
-  return null;
+  return detectDockerHostsFromInterfaces(networkInterfaces);
 }
 
 class AgentTank {
@@ -75,6 +121,7 @@ class AgentTank {
     this.requestedAgents = options.agents || null;
     this.freshProcess = options.freshProcess || false;
     this.claudeApi = options.claudeApi || false; // Use direct Anthropic API for Claude
+    this.geminiMode = options.geminiMode || 'fallback';
     this.auth = options.auth || {};
     this.agents = new Map();
     this.server = null;
@@ -83,6 +130,9 @@ class AgentTank {
     this.publicStatus = {}; // Public API status from upstream providers
     this.skipServer = options.skipServer || false; // Skip HTTP server in one-shot mode
     this.lastRefreshedAt = null;
+    this.refreshCooldown = Math.max(0, options.refreshCooldown ?? 30);
+    this._agentRefreshStartedAt = new Map();
+    this._agentRefreshPromises = new Map();
     this.stopping = false;
 
     // Auto-refresh configuration (backend periodic refresh)
@@ -278,7 +328,7 @@ class AgentTank {
       case 'claude':
         return new ClaudeAgent({ useApi: this.claudeApi });
       case 'gemini':
-        return new GeminiAgent();
+        return new GeminiAgent({ mode: this.geminiMode });
       case 'codex':
         return new CodexAgent();
       default:
@@ -299,10 +349,10 @@ class AgentTank {
     const [, publicStatusResult] = await Promise.all([
       // Agent PTY refreshes
       Promise.all(
-        Array.from(this.agents.values()).map(agent =>
-          agent.refresh().catch(err => {
+        Array.from(this.agents.keys()).map(name =>
+          this._refreshAgentWithCooldown(name).catch(err => {
             if (!this.stopping && err.message !== 'Agent stopping') {
-              logger.error(`Error refreshing ${agent.name}:`, err.message);
+              logger.error(`Error refreshing ${name}:`, err.message);
             }
           })
         )
@@ -347,7 +397,7 @@ class AgentTank {
     if (!agent) {
       throw new Error(`Agent not found: ${name}`);
     }
-    await agent.refresh();
+    await this._refreshAgentWithCooldown(name);
 
     // Record snapshot and attach pace evaluation for single agent refresh
     if (agent.usage) {
@@ -356,6 +406,47 @@ class AgentTank {
     }
   }
 
+  _getRefreshCooldownRemainingMs(name, now = Date.now()) {
+    if (this.refreshCooldown <= 0) {
+      return 0;
+    }
+
+    const lastStartedAt = this._agentRefreshStartedAt.get(name);
+    if (!lastStartedAt) {
+      return 0;
+    }
+
+    return Math.max(0, (this.refreshCooldown * 1000) - (now - lastStartedAt));
+  }
+
+  async _refreshAgentWithCooldown(name) {
+    const agent = this.agents.get(name);
+    if (!agent) {
+      throw new Error(`Agent not found: ${name}`);
+    }
+
+    const activeRefresh = this._agentRefreshPromises.get(name);
+    if (activeRefresh) {
+      logger.agent(name, 'Refresh already in progress, reusing existing refresh');
+      return activeRefresh;
+    }
+
+    const remainingMs = this._getRefreshCooldownRemainingMs(name);
+    if (remainingMs > 0) {
+      logger.agent(name, `Refresh cooldown active, skipping (${Math.ceil(remainingMs / 1000)}s remaining)`);
+      return;
+    }
+
+    this._agentRefreshStartedAt.set(name, Date.now());
+    const refreshPromise = agent.refresh().finally(() => {
+      if (this._agentRefreshPromises.get(name) === refreshPromise) {
+        this._agentRefreshPromises.delete(name);
+      }
+    });
+    this._agentRefreshPromises.set(name, refreshPromise);
+    return refreshPromise;
+  }
+
   /** Get usage history statistics. @returns {Object} */
   getHistoryStats() { return this.historyStore.getStats(); }
 
@@ -447,16 +538,22 @@ class AgentTank {
     });
   }
 
-  _resolveListenHosts(detectHost = detectDockerHost) {
+  _resolveListenHosts(detectHost = detectDockerHosts) {
     if (this.explicitHost) {
       return [this.host];
     }
 
     const hosts = ['127.0.0.1'];
     if (this.dockerAccess) {
-      const dockerHost = detectHost();
-      if (dockerHost && dockerHost !== '127.0.0.1') {
-        hosts.push(dockerHost);
+      const dockerHosts = detectHost();
+      if (dockerHosts) {
+        // Handle both single IP (legacy) and array of IPs
+        const hostList = Array.isArray(dockerHosts) ? dockerHosts : [dockerHosts];
+        for (const h of hostList) {
+          if (h && h !== '127.0.0.1' && !hosts.includes(h)) {
+            hosts.push(h);
+          }
+        }
       }
     }
 
@@ -500,8 +597,15 @@ class AgentTank {
 
   /** Get the auto-refresh configuration. @returns {Object} */
   getAutoRefreshConfig() {
-    return { mode: this.autoRefresh.mode, enabled: this.autoRefresh.enabled, interval: this.autoRefresh.interval, activityDebounce: this.autoRefresh.activityDebounce, lastRefreshedAt: this.autoRefreshManager ? this.autoRefreshManager.getLastRefreshedAt() : null };
+    return {
+      mode: this.autoRefresh.mode,
+      enabled: this.autoRefresh.enabled,
+      interval: this.autoRefresh.interval,
+      activityDebounce: this.autoRefresh.activityDebounce,
+      refreshCooldown: this.refreshCooldown,
+      lastRefreshedAt: this.autoRefreshManager ? this.autoRefreshManager.getLastRefreshedAt() : null
+    };
   }
 }
 
-module.exports = { AgentTank, AUTO_REFRESH_MODES, detectDockerHost };
+module.exports = { AgentTank, AUTO_REFRESH_MODES, detectDockerHosts, detectDockerHostsFromInterfaces };

package/src/server.js

@@ -52,6 +52,7 @@ function createRequestHandler(tank) {
           autoRefresh: {
             enabled: tank.autoRefresh.enabled && tank.autoRefresh.interval > 0,
             interval: tank.autoRefresh.interval, // in seconds
+            refreshCooldown: tank.refreshCooldown,
           },
           lastRefreshedAt: tank.lastRefreshedAt,
         };