Handle Copilot 'unlimited' and percent_remaining

Parse and respect GitHub's explicit premium_interactions fields for Copilot user quota. Added helpers getFirstNestedBoolean and normalizeExplicitPercentRemaining, looked up percent_remaining and unlimited paths, and use explicit percent_remaining when present (including negative values). If the response marks quota as unlimited, return a user_quota result with unlimited:true and percentRemaining defaulting to 100, update formatCopilotQuota to display "Copilot Unlimited", and map the unlimited result to a provider value row showing "Unlimited". Also added the optional unlimited flag to CopilotQuotaResult, updated tests to cover explicit percent, negative percent, and unlimited cases, and documented the behavior in README.

Author: slkiser

README.md

@@ -340,6 +340,8 @@ Run `/quota_status` and check the Anthropic section.
 
 Run `/quota_status` and check `copilot_quota_auth`, `billing_mode`, `billing_scope`, and `quota_api`.
 
+For personal Copilot OAuth quota, the plugin uses GitHub's reported premium-interaction quota fields when available. If that specific quota payload marks premium interactions as unlimited, quota output renders `Unlimited` instead of a synthetic used/total ratio.
+
 | Symptom | Fix |
 | --- | --- |
 | Personal quota missing | Confirm OpenCode Copilot auth works. The plugin can read OpenCode's Copilot OAuth token. |

src/lib/copilot.ts

@@ -189,6 +189,16 @@ function getFirstNestedString(source: unknown, paths: string[][]): string | unde
   return coerceNonEmptyString(getFirstNestedValue(source, paths));
 }
 
+function getFirstNestedBoolean(source: unknown, paths: string[][]): boolean | undefined {
+  const value = getFirstNestedValue(source, paths);
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function normalizeExplicitPercentRemaining(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value)) return undefined;
+  return Math.min(100, Math.floor(value));
+}
+
 function normalizeCopilotTier(value: string | undefined): CopilotTier | undefined {
   const normalized = value?.trim().toLowerCase();
   if (!normalized) return undefined;
@@ -803,6 +813,22 @@ function toUserQuotaResultFromCopilotInternal(response: unknown): CopilotQuotaRe
     ["quota_reset_date"],
     ["quota_reset_at"],
   ];
+  const percentRemainingPaths = [
+    ["quota", "percent_remaining"],
+    ["monthly_quota", "percent_remaining"],
+    ["monthly_premium_requests", "percent_remaining"],
+    ["premium_requests", "percent_remaining"],
+    ["quota_snapshots", "premium_interactions", "percent_remaining"],
+    ["percent_remaining"],
+  ];
+  const unlimitedPaths = [
+    ["quota", "unlimited"],
+    ["monthly_quota", "unlimited"],
+    ["monthly_premium_requests", "unlimited"],
+    ["premium_requests", "unlimited"],
+    ["quota_snapshots", "premium_interactions", "unlimited"],
+    ["unlimited"],
+  ];
   const tierPaths = [
     ["plan", "type"],
     ["plan", "name"],
@@ -815,6 +841,10 @@ function toUserQuotaResultFromCopilotInternal(response: unknown): CopilotQuotaRe
   let total = getFirstNestedNumber(response, totalPaths);
   let used = getFirstNestedNumber(response, usedPaths);
   const remaining = getFirstNestedNumber(response, remainingPaths);
+  const unlimited = getFirstNestedBoolean(response, unlimitedPaths) === true;
+  const explicitPercentRemaining = normalizeExplicitPercentRemaining(
+    getFirstNestedNumber(response, percentRemainingPaths),
+  );
   const resetTimeIso =
     normalizeResetTimeIso(getFirstNestedString(response, resetPaths)) ?? getApproxNextResetIso();
   const tier = normalizeCopilotTier(getFirstNestedString(response, tierPaths));
@@ -829,6 +859,18 @@ function toUserQuotaResultFromCopilotInternal(response: unknown): CopilotQuotaRe
     total = COPILOT_PLAN_LIMITS[tier];
   }
 
+  if (unlimited) {
+    return {
+      success: true,
+      mode: "user_quota",
+      used: Math.max(0, used ?? 0),
+      total: Math.max(1, total ?? 1),
+      percentRemaining: explicitPercentRemaining ?? 100,
+      unlimited: true,
+      resetTimeIso,
+    };
+  }
+
   if (!Number.isFinite(total) || total === undefined || total <= 0 || used === undefined || used < 0) {
     throw new Error(
       "GitHub /copilot_internal/user response did not include usable personal quota fields.",
@@ -840,7 +882,7 @@ function toUserQuotaResultFromCopilotInternal(response: unknown): CopilotQuotaRe
     mode: "user_quota",
     used,
     total,
-    percentRemaining: computePercentRemainingFromUsed({ used, total }),
+    percentRemaining: explicitPercentRemaining ?? computePercentRemainingFromUsed({ used, total }),
     resetTimeIso,
   };
 }
@@ -1111,6 +1153,10 @@ export function formatCopilotQuota(result: CopilotResult): string | null {
     return `Copilot Enterprise (${result.enterprise}) ${details.join(" | ")}`;
   }
 
+  if (result.unlimited) {
+    return "Copilot Unlimited";
+  }
+
   const percentUsed = 100 - result.percentRemaining;
   return `Copilot ${result.used}/${result.total} (${percentUsed}%)`;
 }

src/lib/types.ts

@@ -451,6 +451,7 @@ export interface CopilotQuotaResult {
   used: number;
   total: number;
   percentRemaining: number;
+  unlimited?: boolean;
   resetTimeIso?: string;
 }
 

src/providers/copilot.ts

@@ -92,6 +92,22 @@ export const copilotProvider: QuotaProvider = {
       );
     }
 
+    if (result.unlimited) {
+      return attemptedResult(
+        [
+          {
+            kind: "value",
+            name: "Copilot",
+            group: getCopilotGroup(result.mode),
+            label: "Quota:",
+            value: "Unlimited",
+            resetTimeIso: result.resetTimeIso,
+          },
+        ],
+        [],
+      );
+    }
+
     return attemptedResult(
       [
         {

tests/lib.copilot.test.ts

@@ -244,6 +244,122 @@ describe("queryCopilotQuota", () => {
     expect(String(fetchMock.mock.calls[0]?.[0])).toBe("https://api.github.com/copilot_internal/user");
   });
 
+  it("uses explicit percent_remaining from /copilot_internal/user when present", async () => {
+    authMocks.readAuthFile.mockResolvedValueOnce({
+      "github-copilot": { type: "oauth", access: "oauth_access_token", refresh: "refresh" },
+    });
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            quota_reset_date_utc: "2026-05-01T00:00:00.000Z",
+            quota_snapshots: {
+              premium_interactions: {
+                entitlement: 1500,
+                remaining: 401,
+                percent_remaining: 26.7,
+                unlimited: false,
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+      ) as any,
+    );
+
+    const { queryCopilotQuota } = await import("../src/lib/copilot.js");
+    const result = await queryCopilotQuota();
+
+    expect(result).toEqual({
+      success: true,
+      mode: "user_quota",
+      used: 1099,
+      total: 1500,
+      percentRemaining: 26,
+      resetTimeIso: "2026-05-01T00:00:00.000Z",
+    });
+  });
+
+  it("preserves explicit negative percent_remaining for over-quota responses", async () => {
+    authMocks.readAuthFile.mockResolvedValueOnce({
+      "github-copilot": { type: "oauth", access: "oauth_access_token", refresh: "refresh" },
+    });
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            quota_reset_date_utc: "2026-05-01T00:00:00.000Z",
+            quota_snapshots: {
+              premium_interactions: {
+                entitlement: 300,
+                remaining: -60,
+                percent_remaining: -20,
+                unlimited: false,
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+      ) as any,
+    );
+
+    const { queryCopilotQuota } = await import("../src/lib/copilot.js");
+    const result = await queryCopilotQuota();
+
+    expect(result).toEqual({
+      success: true,
+      mode: "user_quota",
+      used: 360,
+      total: 300,
+      percentRemaining: -20,
+      resetTimeIso: "2026-05-01T00:00:00.000Z",
+    });
+  });
+
+  it("treats explicit unlimited premium_interactions as unlimited", async () => {
+    authMocks.readAuthFile.mockResolvedValueOnce({
+      "github-copilot": { type: "oauth", access: "oauth_access_token", refresh: "refresh" },
+    });
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            quota_reset_date_utc: "2026-04-01T00:00:00.000Z",
+            quota_snapshots: {
+              premium_interactions: {
+                entitlement: 1,
+                remaining: 1,
+                percent_remaining: 100,
+                unlimited: true,
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+      ) as any,
+    );
+
+    const { formatCopilotQuota, queryCopilotQuota } = await import("../src/lib/copilot.js");
+    const result = await queryCopilotQuota();
+
+    expect(result).toEqual({
+      success: true,
+      mode: "user_quota",
+      used: 0,
+      total: 1,
+      percentRemaining: 100,
+      unlimited: true,
+      resetTimeIso: "2026-04-01T00:00:00.000Z",
+    });
+    expect(formatCopilotQuota(result)).toBe("Copilot Unlimited");
+  });
+
   it("returns a clear error when OAuth auth exists without an access token", async () => {
     authMocks.readAuthFile.mockResolvedValueOnce({
       "github-copilot": { type: "oauth", refresh: "refresh_only" },

tests/providers.copilot.test.ts

@@ -47,6 +47,33 @@ describe("copilot provider", () => {
     expect(out.presentation).toBeUndefined();
   });
 
+  it("maps explicit unlimited personal quota into a value row", async () => {
+    const { queryCopilotQuota } = await import("../src/lib/copilot.js");
+    (queryCopilotQuota as any).mockResolvedValueOnce({
+      success: true,
+      mode: "user_quota",
+      used: 0,
+      total: 1,
+      percentRemaining: 100,
+      unlimited: true,
+      resetTimeIso: "2026-02-01T00:00:00.000Z",
+    });
+
+    const out = await copilotProvider.fetch({} as any);
+    expectAttemptedWithNoErrors(out);
+    expect(out.entries).toEqual([
+      {
+        kind: "value",
+        name: "Copilot",
+        group: "Copilot (personal)",
+        label: "Quota:",
+        value: "Unlimited",
+        resetTimeIso: "2026-02-01T00:00:00.000Z",
+      },
+    ]);
+    expect(out.presentation).toBeUndefined();
+  });
+
   it("maps organization usage into a grouped-capable business entry", async () => {
     const { queryCopilotQuota } = await import("../src/lib/copilot.js");
     (queryCopilotQuota as any).mockResolvedValueOnce({