[payne0420]

Summary

Lets operators set a usage cutoff per quota window — e.g. Codex session=95% · weekly=80%, Claude weekly_sonnet=60% · weekly_designer=70%, GLM monthly=50% — so the dispatch loop skips a connection before it hits its upstream limit, with zero latency when nothing is configured.

Before: a single 98% threshold hardcoded into preflight, Codex-only enforcement, no UI to change it. After: per-window thresholds on every provider with usage data (~16 providers via the existing getUsageForProvider), configurable per connection through a modal in Dashboard › Limits.

Routing changes

• Generic quota fetcher (open-sse/services/genericQuotaFetcher.ts) wraps every provider with a getUsageForProvider implementation and surfaces a per-window breakdown to the preflight evaluator. Bespoke fetchers (Codex, CROF, DeepSeek, Bailian Coding Plan) take precedence — the generic registrar skips them.
• preflightQuota iterates each window when the fetcher supplies a windows map and blocks if ANY window crosses its threshold. Names the worst window in the response so logs are actionable. Legacy single-signal path preserved for fetchers without per-window data.
• Cascading resolver in src/sse/services/auth.ts:
  connection.quotaWindowThresholds[window] → resilience.providerWindowDefaults[provider][window] → global defaultThresholdPercent (98%).
• Latency gate: the upstream usage fetch is skipped entirely when no override, no provider default, and no legacy quotaPreflightEnabled flag is set — i.e. zero overhead for the default case.
• USAGE_FETCHER_PROVIDERS exported from usage.ts so the generic registration can't drift from the switch statement.

Storage

• Migration 056 adds quota_window_thresholds_json TEXT to provider_connections.
• Shape: { "<windowName>": <0-100 int> }. Window keys match the quota names surfaced by getUsageForProvider, so the dashboard's quota bars and the persisted overrides reference the same windows.
• Sanitization happens once at the write boundary; the serializer trusts its input.

API

• PUT /api/providers/[id] accepts quotaWindowThresholds with three patch shapes: null (clear all), partial map (merge), per-key null (clear that window). Zod-validates key length (max 64) and value range (0-100).
• New GET /api/providers/quota-windows surfaces resilience-settings defaults so the modal can render per-window placeholders.

UI

• Dashboard › Limits gets a Cutoff column with one button per connection. Button shows Default or a summary like 5h:95% · 7d:80% (clipped to 2 entries + +N).
• Clicking opens a modal listing every window the connection's quota cache exposes, with placeholders showing the resolved default for that (provider, window). Save sends a merge patch; Reset all clears every override on that connection.
• Button is disabled until the connection's quota data has loaded.

Test plan

• Per-window evaluation (block-if-any, omitted-resolver fallback, window-name resolver semantics).
• Generic fetcher conversion (remainingPercentage, used/total, clamp, skip unlimited).
• Resilience settings defaults + clamping + per-provider seeding.
• DB round-trip + sanitization + Zod validation.
• Skip-gate regression: fetcher must not run when no limits are configured.
• Counterpart regression: fetcher must run when an override is set — caught a critical bug where ProviderConnectionView was dropping quotaWindowThresholds/provider/id/email, which would have shipped the feature inert for non-Codex providers. Adding this test surfaced the bug.
• 89/89 quota-related tests + 51/51 sse-auth tests pass; typecheck and lint clean; dev container rebuilt and migration applied cleanly.
• Manual: open Dashboard › Limits with multiple Codex / Claude / GLM connections, set per-window cutoffs, watch routing skip an account when its window crosses the threshold.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a per-window quota preflight system, enabling granular usage enforcement across different time windows for various providers. It includes a new generic fetcher adapter, database migrations for threshold persistence, and a dashboard UI for managing per-connection cutoffs. Feedback highlights a need to generalize JSON column parsing in the database utilities, correct a logic discrepancy in the API route regarding empty threshold maps, and refine the latency gate in the authentication service to respect global default thresholds. There is also a recommendation to ensure consistent object structures between the connection creation and update paths.

[gemini-code-assist]

Hardcoding specific column names like quotaWindowThresholdsJson in a generic utility like rowToCamel is a maintainability issue. This logic should be generalized to handle any column with a Json suffix, which would also simplify the implementation and make it reusable for future features.

    } else if (camelKey.endsWith("Json") && typeof v === "string") {
      const baseKey = camelKey.slice(0, -4);
      try {
        result[baseKey] = JSON.parse(v);
      } catch {
        result[baseKey] = null;
      }

[payne0420]

Agree — generalized in c5b912a. rowToCamel now treats any column whose camel-case key ends in Json as a JSON-encoded TEXT column and surfaces the parsed value under the key minus the suffix (e.g. quotaWindowThresholdsJson → quotaWindowThresholds). Established the same convention for any future _json column.

[gemini-code-assist]

The comment states that an empty map {} should clear every per-window override, but the implementation at lines 170-184 performs a merge. If incomingWindowThresholds is {}, the loop is skipped and existing overrides are preserved. Please either update the logic to clear on {} or correct the comment to reflect that only null clears all overrides.

[payne0420]

Agree the comment was misleading — fixed it in c5b912a. Kept the merge-on-empty behavior (PATCH convention: empty patch = no-op, only explicit null clears all). Comment now reads:

// PATCH semantics:
//   • null            → clear every per-window override on this connection
//   • {} (empty map)  → no-op (no keys to merge); existing overrides preserved
//   • partial map     → merge into the existing map; a `null` value at any
//                        key clears just that window's override

[gemini-code-assist]

The latency gate skips the upstream usage fetch if no per-connection or per-provider overrides are set. However, it does not account for the global defaultThresholdPercent from resilience settings. If an operator sets a restrictive global threshold (e.g., 50%), it will be ignored for all connections without specific overrides, potentially leading to unexpected routing behavior. The gate should also check if the global threshold is restrictive enough (e.g., < 98%) to warrant preflight.

[payne0420]

Good catch — agree. Fixed in c5b912a. The latency gate now also runs preflight when the global defaultThresholdPercent has been raised above the factory no-op level (2% remaining = effectively "right before 429"). Anything stricter (e.g. 20% remaining = stop at 80% used) means the operator wants enforcement and preflight runs.

Added regression test in tests/unit/sse-auth.test.ts: registers a fetcher, tightens the global to 20%, asserts the fetcher fires; resets to factory, asserts the fetcher does NOT fire.

[gemini-code-assist]

The withNullableQuotaWindowThresholds wrapper uses Object.hasOwn to decide whether to add the field, which causes an inconsistency between the create and update paths. In createProviderConnection, the key is deleted if sanitized to null (lines 300-301), causing it to be missing from the returned object. In updateProviderConnection, it is preserved. It is better to remove the hasOwn check to match the behavior of withNullableMaxConcurrent, ensuring the key is always present in the returned object.

  return {
    ...record,
    quotaWindowThresholds: source?.quotaWindowThresholds ?? null,
  };

[payne0420]

Agree — simplified in c5b912a. withNullableQuotaWindowThresholds now always surfaces the field (possibly null), matching withNullableMaxConcurrent's contract. The createProviderConnection code path that used to delete the key when sanitization collapsed to no-overrides is gone; both create and update return the same shape now.

[payne0420]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 165bb0a11e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Treat empty quotaWindowThresholds patch as clear-all

The handler documents {} as “clear every per-window override”, but this branch initializes existingMap from the current stored overrides; when the incoming object is empty, the merge loop is a no-op and the old overrides are written back unchanged. Any client that sends {} (per the API contract/comments) will fail to clear thresholds, leaving quota preflight behavior unexpectedly active.

Useful? React with 👍 / 👎.

[payne0420]

Partial agree: the comment was wrong, the implementation was right. Fixed in c5b912a. Empty {} is intentionally a no-op (PATCH convention — empty patch should preserve state). Only an explicit null for the whole field clears every override. Comment now reflects this:

// PATCH semantics:
//   • null            → clear every per-window override on this connection
//   • {} (empty map)  → no-op (no keys to merge); existing overrides preserved
//   • partial map     → merge into the existing map; a `null` value at any
//                        key clears just that window's override

If you want "clear all" you send { "quotaWindowThresholds": null }, not { "quotaWindowThresholds": {} }.

[chatgpt-codex-connector]

Enforce management auth on quota-windows endpoint

This new providers endpoint returns operational routing policy (providerWindowDefaults and global threshold) but does not call requireManagementAuth, unlike other /api/providers/* management routes. As implemented, unauthenticated callers can fetch internal quota cutoff configuration via GET /api/providers/quota-windows, which is an authorization regression for provider management data.

Useful? React with 👍 / 👎.

[payne0420]

Agree — fixed in c5b912a. GET /api/providers/quota-windows now calls requireManagementAuth before returning anything. Confirmed via curl that an unauthenticated request gets 401, matching sibling /api/providers/* routes.

[diegosouzapw]

Thanks @payne0420! 🚀 This is a fantastic contribution — extending quota preflight from Codex-only to 16+ providers with per-window granularity is a major quality-of-life upgrade for operators. The cascading threshold resolver (connection → provider default → global 98%) is well-architected, and the zero-latency gate for the default case shows great attention to performance. The test suite (89 quota + 51 auth tests) is impressive, and catching the ProviderConnectionView field-dropping regression via tests is excellent practice. Merging into release/v3.8.0.