opencode-gemini-auth 1.3.11 → 1.4.0

package/README.md

@@ -47,6 +47,12 @@ Add the plugin to your Opencode configuration file
 
 Once authenticated, Opencode will use your Google account for Gemini requests.
 
+To check your current Gemini Code Assist quota buckets at any time, run:
+
+```bash
+/gquota
+```
+
 ## Configuration
 
 ### Google Cloud Project

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-gemini-auth",
   "module": "index.ts",
-  "version": "1.3.11",
+  "version": "1.4.0",
   "author": "jenslys",
   "repository": "https://github.com/jenslys/opencode-gemini-auth",
   "files": [
@@ -14,7 +14,7 @@
     "update:gemini-cli": "git -C .local/gemini-cli pull --ff-only"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "^1.1.48",
+    "@opencode-ai/plugin": "^1.2.10",
     "@types/bun": "latest"
   },
   "peerDependencies": {

package/src/plugin/project/api.ts

@@ -4,6 +4,7 @@ import {
   FREE_TIER_ID,
   type LoadCodeAssistPayload,
   type OnboardUserPayload,
+  type RetrieveUserQuotaResponse,
   ProjectIdRequiredError,
 } from "./types";
 import { buildMetadata, isVpcScError, parseJsonSafe, wait } from "./utils";
@@ -131,14 +132,6 @@ export async function onboardManagedProject(
   return undefined;
 }
 
-interface RetrieveUserQuotaBucket {
-  modelId?: string;
-}
-
-interface RetrieveUserQuotaResponse {
-  buckets?: RetrieveUserQuotaBucket[];
-}
-
 /**
  * Retrieves Code Assist quota buckets, which include model IDs visible to the current account/project.
  */

package/src/plugin/project/types.ts

@@ -43,6 +43,18 @@ export interface OnboardUserPayload {
   };
 }
 
+export interface RetrieveUserQuotaBucket {
+  remainingAmount?: string;
+  remainingFraction?: number;
+  resetTime?: string;
+  tokenType?: string;
+  modelId?: string;
+}
+
+export interface RetrieveUserQuotaResponse {
+  buckets?: RetrieveUserQuotaBucket[];
+}
+
 /**
  * Error raised when a required Google Cloud project is missing during Gemini onboarding.
  */

package/src/plugin/quota.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { formatGeminiQuotaOutput, formatRelativeResetTime } from "./quota";
+import type { RetrieveUserQuotaBucket } from "./project/types";
+
+const REAL_DATE_NOW = Date.now;
+const FIXED_NOW = Date.parse("2026-02-21T00:00:00.000Z");
+
+describe("formatRelativeResetTime", () => {
+  beforeEach(() => {
+    Date.now = () => FIXED_NOW;
+  });
+
+  afterEach(() => {
+    Date.now = REAL_DATE_NOW;
+  });
+
+  it("formats future reset times as relative labels", () => {
+    const reset = new Date(FIXED_NOW + 90 * 60 * 1000).toISOString();
+    expect(formatRelativeResetTime(reset)).toBe("resets in 1h 30m");
+  });
+
+  it("returns reset pending when reset time is in the past", () => {
+    const reset = new Date(FIXED_NOW - 60 * 1000).toISOString();
+    expect(formatRelativeResetTime(reset)).toBe("reset pending");
+  });
+});
+
+describe("formatGeminiQuotaOutput", () => {
+  beforeEach(() => {
+    Date.now = () => FIXED_NOW;
+  });
+
+  afterEach(() => {
+    Date.now = REAL_DATE_NOW;
+  });
+
+  it("renders sorted, model-specific usage lines", () => {
+    const buckets: RetrieveUserQuotaBucket[] = [
+      {
+        modelId: "gemini-2.5-pro",
+        tokenType: "requests",
+        remainingFraction: 0.5,
+        remainingAmount: "100",
+        resetTime: new Date(FIXED_NOW + 60 * 60 * 1000).toISOString(),
+      },
+      {
+        modelId: "gemini-2.5-flash",
+        remainingAmount: "20",
+      },
+    ];
+
+    const output = formatGeminiQuotaOutput("test-project", buckets);
+    expect(output).toContain("Gemini quota usage for project `test-project`");
+    expect(output).toContain("- gemini-2.5-flash: 20 remaining");
+    expect(output).toContain(
+      "- gemini-2.5-pro (requests): 50.0% remaining (100 left), resets in 1h",
+    );
+    expect(output.indexOf("gemini-2.5-flash")).toBeLessThan(
+      output.indexOf("gemini-2.5-pro"),
+    );
+  });
+});

package/src/plugin/quota.ts

@@ -0,0 +1,182 @@
+import { tool } from "@opencode-ai/plugin";
+import { accessTokenExpired, isOAuthAuth } from "./auth";
+import { resolveCachedAuth } from "./cache";
+import { ensureProjectContext, retrieveUserQuota } from "./project";
+import type { RetrieveUserQuotaBucket } from "./project/types";
+import { refreshAccessToken } from "./token";
+import type { GetAuth, PluginClient } from "./types";
+
+export const GEMINI_QUOTA_TOOL_NAME = "gemini_quota";
+
+interface GeminiQuotaToolDependencies {
+  client: PluginClient;
+  getAuthResolver: () => GetAuth | undefined;
+  getConfiguredProjectId: () => string | undefined;
+}
+
+export function createGeminiQuotaTool({
+  client,
+  getAuthResolver,
+  getConfiguredProjectId,
+}: GeminiQuotaToolDependencies) {
+  return tool({
+    description:
+      "Retrieve current Gemini Code Assist quota usage for the authenticated user and project.",
+    args: {},
+    async execute() {
+      const getAuth = getAuthResolver();
+      if (!getAuth) {
+        return "Gemini quota is unavailable before Google auth is initialized. Authenticate with the Google provider and retry.";
+      }
+
+      const auth = await getAuth();
+      if (!isOAuthAuth(auth)) {
+        return "Gemini quota requires OAuth with Google. Run `opencode auth login` and choose `OAuth with Google (Gemini CLI)`.";
+      }
+
+      let authRecord = resolveCachedAuth(auth);
+      if (accessTokenExpired(authRecord)) {
+        const refreshed = await refreshAccessToken(authRecord, client);
+        if (!refreshed?.access) {
+          return "Gemini quota lookup failed because the access token could not be refreshed. Re-authenticate and retry.";
+        }
+        authRecord = refreshed;
+      }
+
+      if (!authRecord.access) {
+        return "Gemini quota lookup failed because no access token is available. Re-authenticate and retry.";
+      }
+
+      try {
+        const projectContext = await ensureProjectContext(
+          authRecord,
+          client,
+          getConfiguredProjectId(),
+        );
+        if (!projectContext.effectiveProjectId) {
+          return "Gemini quota lookup failed because no Google Cloud project could be resolved.";
+        }
+
+        const quota = await retrieveUserQuota(
+          authRecord.access,
+          projectContext.effectiveProjectId,
+        );
+        if (!quota?.buckets?.length) {
+          return `No Gemini quota buckets were returned for project \`${projectContext.effectiveProjectId}\`.`;
+        }
+
+        return formatGeminiQuotaOutput(
+          projectContext.effectiveProjectId,
+          quota.buckets,
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error";
+        return `Gemini quota lookup failed: ${message}`;
+      }
+    },
+  });
+}
+
+export function formatGeminiQuotaOutput(
+  projectId: string,
+  buckets: RetrieveUserQuotaBucket[],
+): string {
+  const sortedBuckets = [...buckets].sort(compareQuotaBuckets);
+  const lines = [`Gemini quota usage for project \`${projectId}\``, ""];
+
+  for (const bucket of sortedBuckets) {
+    lines.push(formatQuotaBucketLine(bucket));
+  }
+
+  return lines.join("\n");
+}
+
+function compareQuotaBuckets(
+  left: RetrieveUserQuotaBucket,
+  right: RetrieveUserQuotaBucket,
+): number {
+  const leftModel = left.modelId ?? "";
+  const rightModel = right.modelId ?? "";
+  if (leftModel !== rightModel) {
+    return leftModel.localeCompare(rightModel);
+  }
+
+  const leftTokenType = left.tokenType ?? "";
+  const rightTokenType = right.tokenType ?? "";
+  if (leftTokenType !== rightTokenType) {
+    return leftTokenType.localeCompare(rightTokenType);
+  }
+
+  return (left.resetTime ?? "").localeCompare(right.resetTime ?? "");
+}
+
+function formatQuotaBucketLine(bucket: RetrieveUserQuotaBucket): string {
+  const modelId = bucket.modelId?.trim() || "unknown-model";
+  const tokenType = bucket.tokenType?.trim();
+  const usageRemaining = formatUsageRemaining(bucket);
+  const resetLabel = formatRelativeResetTime(bucket.resetTime);
+  const subject = tokenType ? `${modelId} (${tokenType})` : modelId;
+
+  return resetLabel
+    ? `- ${subject}: ${usageRemaining}, ${resetLabel}`
+    : `- ${subject}: ${usageRemaining}`;
+}
+
+function formatUsageRemaining(bucket: RetrieveUserQuotaBucket): string {
+  const remainingAmount = formatRemainingAmount(bucket.remainingAmount);
+  const remainingFraction = bucket.remainingFraction;
+  const hasFraction =
+    typeof remainingFraction === "number" && Number.isFinite(remainingFraction);
+
+  if (hasFraction) {
+    const percent = Math.max(0, remainingFraction * 100).toFixed(1);
+    return remainingAmount
+      ? `${percent}% remaining (${remainingAmount} left)`
+      : `${percent}% remaining`;
+  }
+
+  if (remainingAmount) {
+    return `${remainingAmount} remaining`;
+  }
+
+  return "remaining unknown";
+}
+
+function formatRemainingAmount(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) {
+    return value;
+  }
+  return parsed.toLocaleString("en-US");
+}
+
+export function formatRelativeResetTime(resetTime: string | undefined): string | undefined {
+  if (!resetTime) {
+    return undefined;
+  }
+
+  const resetAt = new Date(resetTime).getTime();
+  if (Number.isNaN(resetAt)) {
+    return undefined;
+  }
+
+  const diffMs = resetAt - Date.now();
+  if (diffMs <= 0) {
+    return "reset pending";
+  }
+
+  const totalMinutes = Math.ceil(diffMs / (1000 * 60));
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+
+  if (hours > 0 && minutes > 0) {
+    return `resets in ${hours}h ${minutes}m`;
+  }
+  if (hours > 0) {
+    return `resets in ${hours}h`;
+  }
+  return `resets in ${minutes}m`;
+}

package/src/plugin/types.ts

@@ -1,4 +1,6 @@
 import type { GeminiTokenExchangeResult } from "../gemini/oauth";
+import type { Config } from "@opencode-ai/sdk";
+import type { ToolDefinition } from "@opencode-ai/plugin";
 
 export interface OAuthAuthDetails {
   type: "oauth";
@@ -57,6 +59,8 @@ export interface PluginContext {
 }
 
 export interface PluginResult {
+  config?: (config: Config) => Promise<void>;
+  tool?: Record<string, ToolDefinition>;
   auth: {
     provider: string;
     loader: (getAuth: GetAuth, provider: Provider) => Promise<LoaderResult | null>;

package/src/plugin.ts

@@ -3,6 +3,10 @@ import { createOAuthAuthorizeMethod } from "./plugin/oauth-authorize";
 import { accessTokenExpired, isOAuthAuth } from "./plugin/auth";
 import { resolveCachedAuth } from "./plugin/cache";
 import { ensureProjectContext, retrieveUserQuota } from "./plugin/project";
+import {
+  createGeminiQuotaTool,
+  GEMINI_QUOTA_TOOL_NAME,
+} from "./plugin/quota";
 import { isGeminiDebugEnabled, logGeminiDebugMessage, startGeminiDebugRequest } from "./plugin/debug";
 import {
   isGenerativeLanguageRequest,
@@ -21,6 +25,15 @@ import type {
   Provider,
 } from "./plugin/types";
 
+const GEMINI_QUOTA_COMMAND = "gquota";
+const GEMINI_QUOTA_COMMAND_TEMPLATE = `Retrieve Gemini Code Assist quota usage for the current authenticated account.
+
+Immediately call \`${GEMINI_QUOTA_TOOL_NAME}\` with no arguments and return its output verbatim.
+Do not call other tools.
+`;
+let latestGeminiAuthResolver: GetAuth | undefined;
+let latestGeminiConfiguredProjectId: string | undefined;
+
 /**
  * Registers the Gemini OAuth provider for Opencode, handling auth, request rewriting,
  * debug logging, and response normalization for Gemini Code Assist endpoints.
@@ -28,15 +41,31 @@ import type {
 export const GeminiCLIOAuthPlugin = async (
   { client }: PluginContext,
 ): Promise<PluginResult> => ({
+  config: async (config) => {
+    config.command = config.command || {};
+    config.command[GEMINI_QUOTA_COMMAND] = {
+      description: "Show Gemini Code Assist quota usage",
+      template: GEMINI_QUOTA_COMMAND_TEMPLATE,
+    };
+  },
+  tool: {
+    [GEMINI_QUOTA_TOOL_NAME]: createGeminiQuotaTool({
+      client,
+      getAuthResolver: () => latestGeminiAuthResolver,
+      getConfiguredProjectId: () => latestGeminiConfiguredProjectId,
+    }),
+  },
   auth: {
     provider: GEMINI_PROVIDER_ID,
     loader: async (getAuth: GetAuth, provider: Provider): Promise<LoaderResult | null> => {
+      latestGeminiAuthResolver = getAuth;
       const auth = await getAuth();
       if (!isOAuthAuth(auth)) {
         return null;
       }
 
       const configuredProjectId = resolveConfiguredProjectId(provider);
+      latestGeminiConfiguredProjectId = configuredProjectId;
       normalizeProviderModelCosts(provider);
 
       return {