Add right summaries and normalize Synthetic dates

Accept optional provider "right" usage summaries in formatting output and use them as left-adjacent text in tiny and classic layouts (format.ts, toast-format-grouped.ts). Add normalization for Synthetic subscription.renewsAt to parse/validate timestamps and ignore malformed values (synthetic.ts). Update tests to cover rendering of right-side summaries, Synthetic date normalization, numeric-field validation, and various Anthropic fallback/error cases; also ensure quota-status shows Synthetic diagnostics without performing a live fetch. README updated to document Synthetic API expectations.

Author: slkiser

README.md

@@ -538,7 +538,8 @@ For security, provider secrets are read from `SYNTHETIC_API_KEY`, your user/glob
 
 - The plugin calls `GET https://api.synthetic.new/v2/quotas`.
 - It reads `subscription.limit`, `subscription.requests`, and `subscription.renewsAt`.
-- `/quota`, toasts, and the sidebar show one Synthetic row with remaining percent plus a compact `used/limit` summary.
+- Synthetic currently expects numeric JSON values for `subscription.limit` and `subscription.requests`; malformed or stringified values are treated as API-shape errors. Invalid `subscription.renewsAt` values are ignored.
+- `/quota`, toasts, and the sidebar show one Synthetic row with remaining percent plus the same compact `used/limit` summary used by other percent-based providers when that row data is available.
 - `/quota_status` shows a `synthetic` section with API-key diagnostics only; it does not do a live Synthetic fetch there.
 - Allowed env templates are limited to `{env:SYNTHETIC_API_KEY}`.
 

src/lib/format.ts

@@ -62,9 +62,16 @@ export function formatQuotaRows(params: {
 
   const lines: string[] = [];
 
-  const addPercentEntry = (name: string, resetIso: string | undefined, remaining: number) => {
+  const addPercentEntry = (
+    name: string,
+    resetIso: string | undefined,
+    remaining: number,
+    rightSummary?: string,
+  ) => {
     const displayedPercent = resolveDisplayedPercent(remaining, params.percentDisplayMode);
     const percentLabel = formatDisplayedPercentLabel(remaining, params.percentDisplayMode);
+    const summary = rightSummary?.trim() || "";
+    const leftText = summary ? `${name} ${summary}` : name;
 
     // Show reset countdown whenever quota is not fully available.
     // (i.e., any usage at all, or depleted)
@@ -74,7 +81,7 @@ export function formatQuotaRows(params: {
       // In tiny mode: single line with name + time + percent
       const tinyNameCol = maxWidth - separator.length - timeCol - separator.length - percentCol;
       const line = [
-        padRight(name, tinyNameCol),
+        padRight(leftText, tinyNameCol),
         padLeft(timeStr, timeCol),
         padLeft(percentLabel, percentCol),
       ].join(separator);
@@ -86,7 +93,7 @@ export function formatQuotaRows(params: {
     // Time is right-aligned to end of bar
     const timeWidth = Math.max(timeStr.length, timeCol);
     const nameWidth = Math.max(1, barWidth - separator.length - timeWidth);
-    const timeLine = padRight(name, nameWidth) + separator + padLeft(timeStr, timeWidth);
+    const timeLine = padRight(leftText, nameWidth) + separator + padLeft(timeStr, timeWidth);
     lines.push(timeLine.slice(0, barWidth));
 
     // Line 2: bar + percent (percent extends beyond bar width)
@@ -134,7 +141,7 @@ export function formatQuotaRows(params: {
     if (isValueEntry(entry)) {
       addValueEntry(entry.name, entry.resetTimeIso, entry.value);
     } else {
-      addPercentEntry(entry.name, entry.resetTimeIso, entry.percentRemaining);
+      addPercentEntry(entry.name, entry.resetTimeIso, entry.percentRemaining, entry.right);
     }
   }
 

src/lib/synthetic.ts

@@ -43,6 +43,24 @@ function invalidSyntheticResponse(message: string): QuotaError {
   };
 }
 
+function normalizeResetTimeIso(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const parsed = Date.parse(trimmed);
+  if (!Number.isFinite(parsed)) {
+    return undefined;
+  }
+
+  return new Date(parsed).toISOString();
+}
+
 export async function querySyntheticQuota(): Promise<SyntheticResult> {
   const resolved = await resolveSyntheticApiKey();
   if (!resolved) return null;
@@ -80,10 +98,7 @@ export async function querySyntheticQuota(): Promise<SyntheticResult> {
       return invalidSyntheticResponse("Synthetic API response missing subscription.requests");
     }
 
-    const renewsAt =
-      typeof subscription.renewsAt === "string" && subscription.renewsAt.trim().length > 0
-        ? subscription.renewsAt.trim()
-        : undefined;
+    const renewsAt = normalizeResetTimeIso(subscription.renewsAt);
 
     const percentRemaining = clampPercent(((limit - requests) / limit) * 100);
 

src/lib/toast-format-grouped.ts

@@ -120,8 +120,9 @@ export function formatQuotaRowsGrouped(params: {
       if (isTiny) {
         // Tiny: "label  time  XX%" (ignore bar)
         const tinyNameCol = maxWidth - separator.length - timeCol - separator.length - percentCol;
+        const leftText = right ? `${label} ${right}` : label;
         const line = [
-          padRight(label, tinyNameCol),
+          padRight(leftText, tinyNameCol),
           padLeft(timeStr, timeCol),
           padLeft(percentLabel, percentCol),
         ].join(separator);

tests/format.test.ts

@@ -67,6 +67,32 @@ describe("formatQuotaRows", () => {
     expect((barLine.match(/█/g) ?? [])).toHaveLength(2);
   });
 
+  it("renders percent-row usage summaries in classic output when providers supply them", () => {
+    const out = formatQuotaRows({
+      version: "1.0.0",
+      layout: { maxWidth: 50, narrowAt: 42, tinyAt: 32 },
+      entries: [
+        {
+          name: "Synthetic",
+          right: "0/135",
+          percentRemaining: 100,
+        },
+        {
+          name: "Qwen RPM",
+          right: "5/60",
+          percentRemaining: 92,
+          resetTimeIso: "2099-01-01T00:00:00.000Z",
+        },
+      ],
+    });
+
+    expect(out).toContain("Synthetic");
+    expect(out).toContain("0/135");
+    expect(out).toContain("Qwen RPM");
+    expect(out).toContain("5/60");
+    expect(out).toContain("92% left");
+  });
+
   it("shows reset countdown when quota is partially used", () => {
     const out = formatQuotaRows({
       version: "1.0.0",
@@ -176,6 +202,26 @@ describe("formatQuotaRows", () => {
     expect((barLine?.match(/█/g) ?? [])).toHaveLength(2);
   });
 
+  it("renders grouped percent-row usage summaries when providers supply them", () => {
+    const out = formatQuotaRows({
+      version: "1.0.0",
+      style: "grouped",
+      layout: { maxWidth: 50, narrowAt: 42, tinyAt: 32 },
+      entries: [
+        {
+          name: "Synthetic",
+          group: "Synthetic",
+          label: "Quota:",
+          right: "0/135",
+          percentRemaining: 100,
+        },
+      ],
+    });
+
+    expect(out).toContain("Quota: 0/135");
+    expect(out).toContain("100% left");
+  });
+
   it("locks rendered grouped toast ordering for Qwen and OpenAI provider groups", () => {
     const out = formatQuotaRows({
       version: "1.0.0",

tests/lib.anthropic.test.ts

@@ -68,8 +68,19 @@ function mockJsonResponse(body: unknown, status = 200): Response {
   } as unknown as Response;
 }
 
+function mockInvalidJsonResponse(status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: vi.fn().mockRejectedValue(new Error("invalid json")),
+    text: vi.fn().mockResolvedValue("{"),
+  } as unknown as Response;
+}
+
 afterEach(() => {
-  vi.clearAllMocks();
+  execFileMock.mockReset();
+  readFileMock.mockReset();
+  fetchWithTimeoutMock.mockReset();
   clearAnthropicDiagnosticsCacheForTests();
 });
 
@@ -366,6 +377,129 @@ describe("Claude CLI diagnostics", () => {
     expect(readFileMock).toHaveBeenCalledTimes(1);
   });
 
+  it("returns no quota when the Claude OAuth fallback access token is malformed", async () => {
+    mockExecSequence([
+      { stdout: "claude 1.2.3\n" },
+      {
+        stdout: JSON.stringify({
+          authenticated: true,
+        }),
+      },
+    ]);
+    readFileMock.mockResolvedValue(
+      JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 123,
+        },
+      }),
+    );
+
+    const diagnostics = await getAnthropicDiagnostics();
+    expect(diagnostics.quotaSupported).toBe(false);
+    expect(diagnostics.message).toContain("Claude OAuth access token missing");
+
+    const quota = await queryAnthropicQuota();
+    expect(quota?.success).toBe(false);
+    if (quota && !quota.success) {
+      expect(quota.error).toContain("Claude OAuth access token missing");
+    }
+    expect(fetchWithTimeoutMock).not.toHaveBeenCalled();
+  });
+
+  it("returns no quota when the Claude OAuth fallback API returns a non-2xx response", async () => {
+    mockExecSequence([
+      { stdout: "claude 1.2.3\n" },
+      {
+        stdout: JSON.stringify({
+          authenticated: true,
+        }),
+      },
+    ]);
+    readFileMock.mockResolvedValue(
+      JSON.stringify({
+        claudeAiOauth: {
+          accessToken: "oauth-access-token",
+        },
+      }),
+    );
+    fetchWithTimeoutMock.mockResolvedValue({
+      ok: false,
+      status: 429,
+      json: vi.fn(),
+      text: vi.fn().mockResolvedValue("rate\u001b[31m limited"),
+    } as unknown as Response);
+
+    const diagnostics = await getAnthropicDiagnostics();
+    expect(diagnostics.quotaSupported).toBe(false);
+    expect(diagnostics.message).toContain("Anthropic API error 429: rate limited");
+    expect(diagnostics.message).not.toContain("\u001b");
+
+    const quota = await queryAnthropicQuota();
+    expect(quota?.success).toBe(false);
+    if (quota && !quota.success) {
+      expect(quota.error).toContain("Anthropic API error 429: rate limited");
+      expect(quota.error).not.toContain("\u001b");
+    }
+  });
+
+  it("returns no quota when the Claude OAuth fallback API returns invalid JSON", async () => {
+    mockExecSequence([
+      { stdout: "claude 1.2.3\n" },
+      {
+        stdout: JSON.stringify({
+          authenticated: true,
+        }),
+      },
+    ]);
+    readFileMock.mockResolvedValue(
+      JSON.stringify({
+        claudeAiOauth: {
+          accessToken: "oauth-access-token",
+        },
+      }),
+    );
+    fetchWithTimeoutMock.mockResolvedValue(mockInvalidJsonResponse());
+
+    const diagnostics = await getAnthropicDiagnostics();
+    expect(diagnostics.quotaSupported).toBe(false);
+    expect(diagnostics.message).toContain("Failed to parse Anthropic quota response");
+
+    const quota = await queryAnthropicQuota();
+    expect(quota?.success).toBe(false);
+    if (quota && !quota.success) {
+      expect(quota.error).toContain("Failed to parse Anthropic quota response");
+    }
+  });
+
+  it("returns no quota when the Claude OAuth fallback API returns an unexpected JSON shape", async () => {
+    mockExecSequence([
+      { stdout: "claude 1.2.3\n" },
+      {
+        stdout: JSON.stringify({
+          authenticated: true,
+        }),
+      },
+    ]);
+    readFileMock.mockResolvedValue(
+      JSON.stringify({
+        claudeAiOauth: {
+          accessToken: "oauth-access-token",
+        },
+      }),
+    );
+    fetchWithTimeoutMock.mockResolvedValue(mockJsonResponse({ ok: true }));
+
+    const diagnostics = await getAnthropicDiagnostics();
+    expect(diagnostics.quotaSupported).toBe(false);
+    expect(diagnostics.message).toContain("Unexpected Anthropic quota response shape");
+
+    const quota = await queryAnthropicQuota();
+    expect(quota?.success).toBe(false);
+    if (quota && !quota.success) {
+      expect(quota.error).toContain("Unexpected Anthropic quota response shape");
+    }
+  });
+
   it("falls back to plain auth status when --json is unsupported", async () => {
     mockExecSequence([
       { stdout: "Claude CLI version 1.2.3\n" },
@@ -377,6 +511,11 @@ describe("Claude CLI diagnostics", () => {
         stdout: "Authenticated",
       },
     ]);
+    readFileMock.mockRejectedValue(
+      Object.assign(new Error("missing credentials"), {
+        code: "ENOENT",
+      }),
+    );
 
     const diagnostics = await getAnthropicDiagnostics();
 

tests/lib.quota-status.test.ts

@@ -108,6 +108,15 @@ const nanoGptMocks = vi.hoisted(() => ({
   queryNanoGptQuota: vi.fn(async () => null),
 }));
 
+const syntheticMocks = vi.hoisted(() => ({
+  getSyntheticKeyDiagnostics: vi.fn(async () => ({
+    configured: false,
+    source: null,
+    checkedPaths: [],
+  })),
+  querySyntheticQuota: vi.fn(async () => null),
+}));
+
 const openCodeGoMocks = vi.hoisted(() => ({
   getOpenCodeGoConfigDiagnostics: vi.fn(async () => ({
     state: "none" as const,
@@ -182,11 +191,8 @@ vi.mock("../src/lib/anthropic.js", () => ({
 }));
 
 vi.mock("../src/lib/synthetic.js", () => ({
-  getSyntheticKeyDiagnostics: vi.fn(async () => ({
-    configured: false,
-    source: null,
-    checkedPaths: [],
-  })),
+  getSyntheticKeyDiagnostics: syntheticMocks.getSyntheticKeyDiagnostics,
+  querySyntheticQuota: syntheticMocks.querySyntheticQuota,
 }));
 
 vi.mock("../src/lib/chutes.js", () => ({
@@ -675,6 +681,37 @@ describe("buildQuotaStatusReport", () => {
     expect(report).toContain("- seven_day_remaining: 85% reset_at=2026-04-01T00:00:00.000Z");
   });
 
+  it("renders Synthetic diagnostics without performing a live Synthetic fetch", async () => {
+    syntheticMocks.getSyntheticKeyDiagnostics.mockResolvedValueOnce({
+      configured: true,
+      source: "env:SYNTHETIC_API_KEY",
+      checkedPaths: ["env:SYNTHETIC_API_KEY"],
+    });
+
+    const { buildQuotaStatusReport } = await import("../src/lib/quota-status.js");
+    const report = await buildQuotaStatusReport({
+      configSource: "test",
+      configPaths: [],
+      enabledProviders: ["synthetic"],
+      alibabaCodingPlanTier: "lite",
+      cursorPlan: "none",
+      pricingSnapshotSource: "auto",
+      onlyCurrentModel: false,
+      providerAvailability: [
+        {
+          id: "synthetic",
+          enabled: true,
+          available: true,
+        },
+      ],
+      generatedAtMs: Date.UTC(2026, 2, 12, 12, 45, 0),
+    });
+
+    expect(report).toContain("synthetic:");
+    expect(report).toContain("- synthetic api key: configured=true source=env:SYNTHETIC_API_KEY");
+    expect(syntheticMocks.querySyntheticQuota).not.toHaveBeenCalled();
+  });
+
   it("reports NanoGPT live subscription and balance diagnostics when configured", async () => {
     nanoGptMocks.getNanoGptKeyDiagnostics.mockResolvedValueOnce({
       configured: true,