@opengeni/config 3.2.1 → 3.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Credit pricing for deployment-funded live (speech-to-speech) voice.
3
+ *
4
+ * Live voice is metered by server-observed connection time, billed per started
5
+ * minute. Prices are deployment configuration, never code defaults: when credit
6
+ * billing is active, a deployment-funded voice model without a configured price
7
+ * is not offered and cannot be started.
8
+ */
9
+ export type RealtimeVoicePricing = {
10
+ /** Upstream cost of one minute of live voice, in USD micros. */
11
+ microsPerMinute: number;
12
+ /** Opengeni margin in basis points added on top of the upstream cost. */
13
+ marginBps?: number | undefined;
14
+ };
15
+ /** Model id of the deployment-hosted Azure GPT Live voice. */
16
+ export declare const AZURE_LIVE_REALTIME_MODEL_ID: "opengeni-azure/gpt-live-1";
17
+ /** One live-voice price, e.g. `{"microsPerMinute":50000,"marginBps":500}`. */
18
+ export declare function parseRealtimeVoicePricingJson(raw: string | undefined, env?: string): RealtimeVoicePricing | null;
19
+ /**
20
+ * Prices keyed by upstream AI Gateway realtime model id, e.g.
21
+ * `{"openai/gpt-realtime-2.1":{"microsPerMinute":120000,"marginBps":500}}`.
22
+ */
23
+ export declare function parseRealtimeVoicePricingTableJson(raw: string | undefined, env?: string): Record<string, RealtimeVoicePricing>;
24
+ /** Credit price of one started minute, after margin, rounded up to whole micros. */
25
+ export declare function realtimeVoiceMinuteCreditMicros(pricing: RealtimeVoicePricing, marginBpsOverride?: number): {
26
+ providerCostMicros: number;
27
+ creditCostMicros: number;
28
+ };
29
+ /** Billed minutes for a server-observed interval: every started minute, at least one. */
30
+ export declare function realtimeVoiceStartedMinutes(startedAt: Date, observedUntil: Date): number;
@@ -0,0 +1,17 @@
1
+ /** Stable account affinity shared by subscription providers. Candidate order is durable creation order. */
2
+ export declare function subscriptionAccountShardIndex(sessionId: string, candidateCount: number): number;
3
+ /**
4
+ * Manual pins are binding even when unavailable. Policy homes remain sticky only
5
+ * while rotation is on; an exhausted home re-shards over the eligible survivors.
6
+ * Selection never changes the pool's active pointer.
7
+ */
8
+ export declare function selectSubscriptionAccount<T extends {
9
+ id: string;
10
+ }>(input: {
11
+ sessionId: string;
12
+ eligible: readonly T[];
13
+ rotationEnabled: boolean;
14
+ activeCredentialId: string | null;
15
+ pinnedCredentialId: string | null;
16
+ pinSource: "manual" | "policy" | null;
17
+ }): T | null;
@@ -0,0 +1,177 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Provider-agnostic web search: the deployment-funded `web_search` and
4
+ * `web_fetch` agent tools.
5
+ *
6
+ * Hosted search (the provider-executed `web_search` tool of the model's own
7
+ * API) follows the model catalog. Provider search is a separate,
8
+ * deployment-configured HTTP provider that Opengeni calls from the worker.
9
+ * Search and page reading are separate slots; each slot holds an ordered
10
+ * list of providers, and a call moves to the next provider when one fails.
11
+ * By default the provider tools are offered only where the turn has no
12
+ * hosted search (`OPENGENI_WEB_SEARCH_PREFER=native`).
13
+ *
14
+ * Adding a provider means one catalog entry here plus one adapter in
15
+ * `@opengeni/runtime/web-search`.
16
+ */
17
+ export declare const WEB_SEARCH_PROVIDER_IDS: readonly ["tinyfish", "parallel", "perplexity", "exa", "tavily", "firecrawl", "brave", "jina", "searxng"];
18
+ export type WebSearchProviderId = (typeof WEB_SEARCH_PROVIDER_IDS)[number];
19
+ /** Used when `OPENGENI_WEB_SEARCH_PROVIDER` is unset: free with an account key. */
20
+ export declare const DEFAULT_WEB_SEARCH_PROVIDER: WebSearchProviderId;
21
+ /** Model-visible names of the provider tools. */
22
+ export declare const WEB_SEARCH_TOOL_NAME = "web_search";
23
+ export declare const WEB_FETCH_TOOL_NAME = "web_fetch";
24
+ export type WebSearchProviderToolName = typeof WEB_SEARCH_TOOL_NAME | typeof WEB_FETCH_TOOL_NAME;
25
+ /**
26
+ * `native` (default): offer provider tools only to turns without hosted
27
+ * search. `provider`: offer them to every turn and withhold the SDK-hosted
28
+ * `web_search` tool. SuperGrok keeps its transport-level native search either
29
+ * way because Opengeni does not attach it as an agent tool.
30
+ */
31
+ export declare const WebSearchPreference: z.ZodEnum<{
32
+ native: "native";
33
+ provider: "provider";
34
+ }>;
35
+ export type WebSearchPreference = z.infer<typeof WebSearchPreference>;
36
+ /** One operation (search or page fetch) a provider offers. */
37
+ export type WebSearchProviderOperation = {
38
+ /** Pay-as-you-go list price of one successful call, in USD micros. */
39
+ listPriceMicros: number;
40
+ /** The operation needs an API key; keyless calls are billed as free. */
41
+ keyRequired: boolean;
42
+ /** Default API base URL; null when the operator must supply one. */
43
+ defaultBaseUrl: string | null;
44
+ };
45
+ export type WebSearchProviderCatalogEntry = {
46
+ id: WebSearchProviderId;
47
+ label: string;
48
+ search: WebSearchProviderOperation | null;
49
+ fetch: WebSearchProviderOperation | null;
50
+ /** Where the list price comes from (checked 2026-10). */
51
+ pricingUrl: string;
52
+ };
53
+ /**
54
+ * Every supported provider with its capabilities, default endpoints and
55
+ * list prices. A provider response that reports its own dollar cost (Exa
56
+ * `costDollars`, Tavily `usage.credits`) bills that cost instead, and
57
+ * `OPENGENI_WEB_SEARCH_PRICING_JSON` overrides both.
58
+ */
59
+ export declare const WEB_SEARCH_PROVIDER_CATALOG: Readonly<Record<WebSearchProviderId, WebSearchProviderCatalogEntry>>;
60
+ /** Per-provider API key variable, e.g. `OPENGENI_WEB_TINYFISH_API_KEY`. */
61
+ export declare function webSearchProviderApiKeyEnv(id: WebSearchProviderId): string;
62
+ /** Per-provider base URL variable, e.g. `OPENGENI_WEB_SEARXNG_BASE_URL`. */
63
+ export declare function webSearchProviderBaseUrlEnv(id: WebSearchProviderId): string;
64
+ /** Every environment variable that configures provider web search. */
65
+ export declare function webSearchEnvironmentVariables(): string[];
66
+ export type WebSearchProviderCredentials = Partial<Record<string, {
67
+ apiKey?: string | undefined;
68
+ baseUrl?: string | undefined;
69
+ }>>;
70
+ export declare const WebSearchProviderCredentialsSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
71
+ apiKey: z.ZodOptional<z.ZodString>;
72
+ baseUrl: z.ZodOptional<z.ZodString>;
73
+ }, z.core.$strict>>>;
74
+ /** Per-provider keys and base URLs from the environment. */
75
+ export declare function webSearchProviderCredentialsFromEnv(source: Record<string, string | undefined>): WebSearchProviderCredentials;
76
+ /**
77
+ * Upstream price of one call in integer USD micros, plus the Opengeni
78
+ * margin in basis points (500 = +5%, as for model pricing). Credit billing
79
+ * charges `ceil(providerCost * (10000 + marginBps) / 10000)` per call.
80
+ */
81
+ export type WebSearchPricing = {
82
+ searchMicros: number;
83
+ fetchMicros: number;
84
+ marginBps?: number | undefined;
85
+ };
86
+ /** Tavily's pay-as-you-go price of one credit, used for reported usage. */
87
+ export declare const TAVILY_CREDIT_MICROS = 8000;
88
+ export type WebSearchProviderEndpoint = {
89
+ provider: WebSearchProviderId;
90
+ apiKey: string | null;
91
+ baseUrl: string | null;
92
+ };
93
+ export type WebSearchProviderConfig = {
94
+ preference: WebSearchPreference;
95
+ /** Search providers in failover order; never empty. */
96
+ search: WebSearchProviderEndpoint[];
97
+ /** Page readers in failover order; empty when pages cannot be fetched. */
98
+ fetch: WebSearchProviderEndpoint[];
99
+ /** Explicit operator prices by provider, overriding list prices. */
100
+ pricingOverrides: Partial<Record<WebSearchProviderId, WebSearchPricing>>;
101
+ /** Deployment-wide margin override for provider-rate credit billing. */
102
+ creditMarginBpsOverride?: number | undefined;
103
+ timeoutMs: number;
104
+ };
105
+ export type WebSearchSettings = {
106
+ webSearchEnabled: boolean;
107
+ webSearchProvider?: string | undefined;
108
+ webFetchProvider?: string | undefined;
109
+ webSearchPrefer?: string | undefined;
110
+ /** Per-provider keys and base URLs (`OPENGENI_WEB_<PROVIDER>_API_KEY` / `_BASE_URL`). */
111
+ webSearchProviderCredentials?: WebSearchProviderCredentials | undefined;
112
+ /** Earlier single-provider settings: apply to the first provider of their slot. */
113
+ webSearchApiKey?: string | undefined;
114
+ webSearchBaseUrl?: string | undefined;
115
+ webFetchApiKey?: string | undefined;
116
+ webFetchBaseUrl?: string | undefined;
117
+ webSearchProviderMode?: string | undefined;
118
+ webSearchPricingJson?: string | undefined;
119
+ webSearchRequestTimeoutMs?: number | undefined;
120
+ /** Credit billing is active for this deployment (see webSearchCreditBillingActive). */
121
+ billingMode?: string | undefined;
122
+ usageLimitsMode?: string | undefined;
123
+ creditMarginBpsOverride?: number | undefined;
124
+ };
125
+ export type WebSearchProviderResolution = {
126
+ status: "off";
127
+ } | {
128
+ status: "invalid";
129
+ reason: string;
130
+ } | {
131
+ status: "configured";
132
+ config: WebSearchProviderConfig;
133
+ };
134
+ /**
135
+ * Resolve the deployment's provider search. `off` applies when
136
+ * `OPENGENI_WEB_SEARCH_ENABLED=false` (the server-wide web search switch),
137
+ * when the provider is `none`, and when the provider is left at its default
138
+ * (TinyFish) without that provider's key. `invalid` means an operator named
139
+ * providers but the configuration cannot work; the tools stay unoffered and
140
+ * the worker logs the reason.
141
+ */
142
+ export declare function resolveWebSearchProvider(settings: WebSearchSettings): WebSearchProviderResolution;
143
+ /** The configured provider, or null when off or invalid. */
144
+ export declare function webSearchProviderConfig(settings: WebSearchSettings): WebSearchProviderConfig | null;
145
+ /**
146
+ * The single web-search plan for one turn, shared by the worker (which tools
147
+ * it attaches) and the API's effective-tools projection (what it reports).
148
+ *
149
+ * `hostedWebSearch` is whether the resolved model attaches the SDK-hosted
150
+ * `web_search` tool. `transportHostedSearch` is true for providers whose native
151
+ * search is added by the transport rather than as an agent tool (SuperGrok).
152
+ */
153
+ export declare function webSearchToolPlan(settings: WebSearchSettings, turn: {
154
+ hostedWebSearch: boolean;
155
+ transportHostedSearch?: boolean;
156
+ /**
157
+ * The workspace turned Opengeni credits off: a provider tool is offered
158
+ * only when one of its providers is free (admission still refuses paid
159
+ * calls if the switch flips mid-turn).
160
+ */
161
+ creditsDisabled?: boolean;
162
+ }): {
163
+ hostedWebSearch: boolean;
164
+ providerTools: WebSearchProviderToolName[];
165
+ };
166
+ /** Whether this deployment bills web search and fetch in Opengeni credits. */
167
+ export declare function webSearchCreditBillingActive(settings: Pick<WebSearchSettings, "billingMode" | "usageLimitsMode">): boolean;
168
+ /** Whether every provider of this tool would spend Opengeni credits per call. */
169
+ export declare function webSearchToolSpendsCredits(settings: WebSearchSettings, config: WebSearchProviderConfig, tool: WebSearchProviderToolName): boolean;
170
+ /** Upstream price for one call to one provider, before any provider-reported cost. */
171
+ export declare function webSearchCallPricing(config: Pick<WebSearchProviderConfig, "pricingOverrides" | "creditMarginBpsOverride">, endpoint: WebSearchProviderEndpoint, operation: "search" | "fetch"): {
172
+ providerMicros: number;
173
+ marginBps: number;
174
+ explicit: boolean;
175
+ };
176
+ /** Credit cost of a provider cost after margin, rounded up to whole micros. */
177
+ export declare function webSearchCreditMicros(providerMicros: number, marginBps: number): number;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@opengeni/config",
3
- "version": "3.2.1",
4
- "description": "OpenGeni runtime configuration: settings resolution, deployment knobs, and config validation shared across the server packages.",
3
+ "version": "3.2.2",
4
+ "description": "Opengeni runtime configuration: settings resolution, deployment knobs, and config validation shared across the server packages.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -33,9 +33,9 @@
33
33
  "prepublishOnly": "bash ../../scripts/prepublish-guard"
34
34
  },
35
35
  "dependencies": {
36
- "@opengeni/codex": "^0.2.31",
37
- "@opengeni/contracts": "^5.6.0",
38
- "@opengeni/xai-subscription": "^0.1.5",
36
+ "@opengeni/codex": "3.2.2",
37
+ "@opengeni/contracts": "3.2.2",
38
+ "@opengeni/xai-subscription": "3.2.2",
39
39
  "zod": "^4.2.1"
40
40
  },
41
41
  "engines": {
@@ -0,0 +1,129 @@
1
+ import type { ClaudeSubscriptionUsage, ClaudeUsageWindow } from "@opengeni/contracts";
2
+
3
+ const UNKNOWN_RESET_RECHECK_MS = 60_000;
4
+ const allowed = (status: ClaudeUsageWindow["status"]) =>
5
+ status === "allowed" || status === "allowed_warning";
6
+
7
+ /** Evaluate provider-reported plan capacity and its explicitly allowed paid fallback. */
8
+ export function claudeSubscriptionCapacity(
9
+ usage: ClaudeSubscriptionUsage,
10
+ upstreamModelId: string,
11
+ now: Date,
12
+ options: { allowOverage?: boolean } = {},
13
+ ): { available: boolean; nextCheckAt: Date | null; blockingWindows: ClaudeUsageWindow["id"][] } {
14
+ const available = { available: true, nextCheckAt: null, blockingWindows: [] };
15
+ if (!usage.connected || usage.refreshStatus === "reconnect")
16
+ return { ...available, available: false };
17
+ const relevant = (id: ClaudeUsageWindow["id"]): boolean => {
18
+ if (id === "seven_day_opus") return /^claude-opus-/.test(upstreamModelId);
19
+ if (id === "seven_day_sonnet") return /^claude-sonnet-/.test(upstreamModelId);
20
+ return id === "five_hour" || id === "seven_day";
21
+ };
22
+ const applicable = usage.windows.filter((window) => relevant(window.id));
23
+ const relevantClaim = (id: ClaudeUsageWindow["id"] | null) =>
24
+ id === "seven_day_opus" || id === "seven_day_sonnet" ? relevant(id) : true;
25
+ const restrictions = (usage.requestRestrictions ?? []).filter(
26
+ (item) =>
27
+ item.status === "rejected" &&
28
+ (item.upstreamModelId === upstreamModelId ||
29
+ (item.upstreamModelId === null && relevantClaim(item.representativeClaim))) &&
30
+ !applicable.some(
31
+ (window) =>
32
+ window.source === "provider" &&
33
+ window.usedPercent !== null &&
34
+ window.usedPercent < 100 &&
35
+ window.id === item.representativeClaim &&
36
+ window.observedAt > item.observedAt,
37
+ ) &&
38
+ (item.resetsAt
39
+ ? Date.parse(item.resetsAt)
40
+ : Date.parse(item.observedAt) + UNKNOWN_RESET_RECHECK_MS) > now.getTime(),
41
+ );
42
+ const blocking = applicable.filter((window) => {
43
+ if (
44
+ (window.resetsAt
45
+ ? Date.parse(window.resetsAt)
46
+ : Date.parse(window.observedAt) + UNKNOWN_RESET_RECHECK_MS) <= now.getTime()
47
+ )
48
+ return false;
49
+ return (
50
+ window.status === "rejected" || (window.status === null && (window.usedPercent ?? 0) >= 100)
51
+ );
52
+ });
53
+ const request = usage.requestStatus;
54
+ const exactModel = request?.upstreamModelId === upstreamModelId;
55
+ const relevantRequest =
56
+ request &&
57
+ (exactModel ||
58
+ (request.upstreamModelId === null && relevantClaim(request.representativeClaim)));
59
+ const freshRequest =
60
+ relevantRequest &&
61
+ applicable.every((window) => window.observedAt <= request.observedAt) &&
62
+ restrictions.every((item) => item.observedAt <= request.observedAt);
63
+ const planResetElapsed =
64
+ request &&
65
+ (request.resetsAt
66
+ ? Date.parse(request.resetsAt)
67
+ : Date.parse(request.observedAt) + UNKNOWN_RESET_RECHECK_MS) <= now.getTime();
68
+ const exactAllowance = (usage.requestRestrictions ?? []).find(
69
+ (item) =>
70
+ item.upstreamModelId === upstreamModelId &&
71
+ allowed(item.status) &&
72
+ blocking.every((window) => window.observedAt < item.observedAt) &&
73
+ restrictions.every((restriction) => restriction.observedAt < item.observedAt),
74
+ );
75
+ if (exactAllowance) return available;
76
+ // An allowed response for Sonnet never overrides an independently observed
77
+ // Opus cap. Only the exact model's fresh response proves overall dispatch.
78
+ if (freshRequest && exactModel && allowed(request.status) && !planResetElapsed) return available;
79
+ const mayUseOverage = options.allowOverage !== false;
80
+ const overageResetElapsed =
81
+ request?.overageResetsAt && Date.parse(request.overageResetsAt) <= now.getTime();
82
+ if (
83
+ freshRequest &&
84
+ request.status === "rejected" &&
85
+ mayUseOverage &&
86
+ allowed(request.overageStatus) &&
87
+ !overageResetElapsed
88
+ )
89
+ return available;
90
+ const rejectedRequest = freshRequest && request.status === "rejected" && !planResetElapsed;
91
+ if (blocking.length === 0 && !rejectedRequest && restrictions.length === 0) return available;
92
+ // An extra-usage balance is a separate fallback. Its rejection does not block
93
+ // an available base plan or delay the next base-plan reset to a monthly date.
94
+ const resets = blocking.map((window) =>
95
+ window.resetsAt
96
+ ? Date.parse(window.resetsAt)
97
+ : Date.parse(window.observedAt) + UNKNOWN_RESET_RECHECK_MS,
98
+ );
99
+ if (rejectedRequest)
100
+ resets.push(
101
+ request.resetsAt
102
+ ? Date.parse(request.resetsAt)
103
+ : Date.parse(request.observedAt) + UNKNOWN_RESET_RECHECK_MS,
104
+ );
105
+ resets.push(
106
+ ...restrictions.map((item) =>
107
+ item.resetsAt
108
+ ? Date.parse(item.resetsAt)
109
+ : Date.parse(item.observedAt) + UNKNOWN_RESET_RECHECK_MS,
110
+ ),
111
+ );
112
+ let nextCheckAt = Math.max(...resets);
113
+ if (
114
+ rejectedRequest &&
115
+ mayUseOverage &&
116
+ request.overageStatus === "rejected" &&
117
+ request.overageResetsAt
118
+ ) {
119
+ const overageReset = Date.parse(request.overageResetsAt);
120
+ // A known reset permits a new authoritative probe, never invents a reading.
121
+ if (overageReset <= now.getTime()) return available;
122
+ nextCheckAt = Math.min(nextCheckAt, overageReset);
123
+ }
124
+ return {
125
+ available: false,
126
+ nextCheckAt: new Date(nextCheckAt),
127
+ blockingWindows: blocking.map((window) => window.id),
128
+ };
129
+ }
@@ -2,12 +2,15 @@ import {
2
2
  ClaudeUsageWindowId,
3
3
  type ClaudeSubscriptionUsage,
4
4
  type ClaudeUsageWindow,
5
+ type ClaudeUsageRequestStatus,
5
6
  } from "@opengeni/contracts";
6
7
 
7
8
  export type ClaudeUsageObservation = {
8
9
  windows: ClaudeUsageWindow[];
9
10
  observedAt: string;
10
11
  source: "response_headers" | "provider";
12
+ requestStatus?: ClaudeUsageRequestStatus | null;
13
+ requestRestrictions?: ClaudeUsageRequestStatus[];
11
14
  };
12
15
  const prefixes: Record<string, string[]> = {
13
16
  five_hour: ["5h"],
@@ -31,9 +34,50 @@ function status(value: unknown): ClaudeUsageWindow["status"] {
31
34
  return value === "allowed" || value === "allowed_warning" || value === "rejected" ? value : null;
32
35
  }
33
36
 
37
+ function latestReset(left: string | null, right: string | null, observedAt: string): string {
38
+ return new Date(
39
+ Math.max(
40
+ left ? Date.parse(left) : Date.parse(observedAt) + 60_000,
41
+ right ? Date.parse(right) : Date.parse(observedAt) + 60_000,
42
+ ),
43
+ ).toISOString();
44
+ }
45
+
46
+ function evidenceKey(item: ClaudeUsageRequestStatus): string {
47
+ // A legacy Sonnet claim does not prove an account-wide restriction cleared.
48
+ return JSON.stringify([
49
+ item.upstreamModelId,
50
+ item.upstreamModelId ? null : item.representativeClaim,
51
+ item.source === "provider",
52
+ ]);
53
+ }
54
+
55
+ function tiedRequest(
56
+ left: ClaudeUsageRequestStatus,
57
+ right: ClaudeUsageRequestStatus,
58
+ ): ClaudeUsageRequestStatus {
59
+ const denied = left.status === "rejected" ? left : right.status === "rejected" ? right : null;
60
+ return {
61
+ ...(denied ?? left),
62
+ resetsAt: denied
63
+ ? latestReset(
64
+ left.status === "rejected" ? left.resetsAt : denied.resetsAt,
65
+ right.status === "rejected" ? right.resetsAt : denied.resetsAt,
66
+ left.observedAt,
67
+ )
68
+ : null,
69
+ representativeClaim:
70
+ left.representativeClaim === right.representativeClaim ? left.representativeClaim : null,
71
+ status: denied ? "rejected" : null,
72
+ overageStatus: null,
73
+ overageResetsAt: null,
74
+ };
75
+ }
76
+
34
77
  export function parseClaudeUsageHeaders(
35
78
  headers: Headers,
36
79
  now = new Date(),
80
+ upstreamModelId?: string,
37
81
  ): ClaudeUsageObservation | null {
38
82
  const observedAt = now.toISOString();
39
83
  const claim = ClaudeUsageWindowId.safeParse(
@@ -41,6 +85,8 @@ export function parseClaudeUsageHeaders(
41
85
  );
42
86
  const claimedStatus = status(headers.get("anthropic-ratelimit-unified-status"));
43
87
  const claimedReset = epoch(headers.get("anthropic-ratelimit-unified-reset"));
88
+ const overageStatus = status(headers.get("anthropic-ratelimit-unified-overage-status"));
89
+ const overageResetsAt = epoch(headers.get("anthropic-ratelimit-unified-overage-reset"));
44
90
  const windows = ClaudeUsageWindowId.options.flatMap((id) => {
45
91
  const header = (suffix: string) =>
46
92
  prefixes[id]!.map((prefix) =>
@@ -53,7 +99,22 @@ export function parseClaudeUsageHeaders(
53
99
  if (usedPercent === null && resetsAt === null && windowStatus === null) return [];
54
100
  return [{ id, usedPercent, resetsAt, status: windowStatus, observedAt }];
55
101
  });
56
- return windows.length ? { windows, observedAt, source: "response_headers" } : null;
102
+ return windows.length || claimedStatus || overageStatus
103
+ ? {
104
+ windows,
105
+ observedAt,
106
+ source: "response_headers",
107
+ requestStatus: {
108
+ status: claimedStatus,
109
+ resetsAt: claimedReset,
110
+ representativeClaim: claim.success ? claim.data : null,
111
+ overageStatus,
112
+ overageResetsAt,
113
+ upstreamModelId: upstreamModelId ?? null,
114
+ observedAt,
115
+ },
116
+ }
117
+ : null;
57
118
  }
58
119
 
59
120
  export function parseClaudeUsageResponse(
@@ -93,16 +154,175 @@ export function mergeClaudeUsage(
93
154
  observation: ClaudeUsageObservation,
94
155
  ): ClaudeSubscriptionUsage {
95
156
  const windows = new Map(current.windows.map((window) => [window.id, window]));
96
- for (const window of observation.windows) {
157
+ for (const incomingWindow of observation.windows) {
158
+ const window = { ...incomingWindow, source: incomingWindow.source ?? observation.source };
97
159
  const previous = windows.get(window.id);
98
- if (!previous || previous.observedAt <= window.observedAt) windows.set(window.id, window);
160
+ if (!previous || previous.observedAt < window.observedAt) windows.set(window.id, window);
161
+ else if (
162
+ previous.observedAt === window.observedAt &&
163
+ JSON.stringify(previous) !== JSON.stringify(window)
164
+ ) {
165
+ const rejected = previous.status === "rejected" || window.status === "rejected";
166
+ const full = (previous.usedPercent ?? 0) >= 100 || (window.usedPercent ?? 0) >= 100;
167
+ windows.set(window.id, {
168
+ ...previous,
169
+ usedPercent:
170
+ previous.usedPercent === null
171
+ ? window.usedPercent
172
+ : window.usedPercent === null
173
+ ? previous.usedPercent
174
+ : Math.max(previous.usedPercent, window.usedPercent),
175
+ status: rejected ? "rejected" : previous.status === window.status ? previous.status : null,
176
+ resetsAt:
177
+ rejected || full
178
+ ? latestReset(previous.resetsAt, window.resetsAt, window.observedAt)
179
+ : previous.resetsAt === window.resetsAt
180
+ ? previous.resetsAt
181
+ : null,
182
+ source:
183
+ previous.source === "response_headers" || window.source === "response_headers"
184
+ ? "response_headers"
185
+ : "provider",
186
+ });
187
+ }
188
+ }
189
+ const incoming = observation.requestStatus;
190
+ const restrictions = new Map(
191
+ (current.requestRestrictions ?? []).map((item) => [evidenceKey(item), item]),
192
+ );
193
+ // Legacy snapshots also contribute their denial; a different model's success
194
+ // must not erase a restriction with an unknown representative claim.
195
+ for (const item of [
196
+ current.requestStatus?.status ? current.requestStatus : null,
197
+ ...(observation.requestRestrictions ?? []),
198
+ incoming?.status ? incoming : null,
199
+ ]) {
200
+ if (!item) continue;
201
+ const key = evidenceKey(item);
202
+ const previous = restrictions.get(key);
203
+ const sanitized = {
204
+ ...item,
205
+ overageStatus: null,
206
+ overageResetsAt: null,
207
+ };
208
+ if (!previous || item.observedAt > previous.observedAt) restrictions.set(key, sanitized);
209
+ else if (
210
+ item.observedAt === previous.observedAt &&
211
+ JSON.stringify(previous) !== JSON.stringify(sanitized)
212
+ )
213
+ restrictions.set(key, tiedRequest(previous, sanitized));
214
+ }
215
+ // Direct refreshes can precede late turn finalizers. Retain each direct
216
+ // window's watermark even when no model restriction is present yet.
217
+ const directWindows = [
218
+ ...current.windows.filter(
219
+ (window) =>
220
+ window.source === "provider" ||
221
+ (!window.source &&
222
+ current.source === "provider" &&
223
+ current.observedAt === window.observedAt),
224
+ ),
225
+ ...observation.windows.filter((window) => (window.source ?? observation.source) === "provider"),
226
+ ];
227
+ for (const window of directWindows) {
228
+ if (window.usedPercent === null || window.usedPercent >= 100) continue;
229
+ const proof: ClaudeUsageRequestStatus = {
230
+ status: null,
231
+ resetsAt: null,
232
+ representativeClaim: window.id,
233
+ upstreamModelId: null,
234
+ overageStatus: null,
235
+ overageResetsAt: null,
236
+ observedAt: window.observedAt,
237
+ source: "provider",
238
+ };
239
+ const key = evidenceKey(proof);
240
+ if (!restrictions.has(key) || restrictions.get(key)!.observedAt < proof.observedAt)
241
+ restrictions.set(key, proof);
242
+ }
243
+ for (const [key, item] of restrictions) {
244
+ if (item.status !== "rejected") continue;
245
+ const proof = [...restrictions.values()].find(
246
+ (candidate) =>
247
+ candidate.source === "provider" &&
248
+ candidate.representativeClaim === item.representativeClaim &&
249
+ candidate.observedAt > item.observedAt &&
250
+ candidate.representativeClaim !== "overage" &&
251
+ candidate.representativeClaim !== "seven_day_overage_included",
252
+ );
253
+ if (proof)
254
+ restrictions.set(key, {
255
+ ...item,
256
+ status: null,
257
+ resetsAt: null,
258
+ observedAt: proof.observedAt,
259
+ });
260
+ }
261
+ // Bound persisted state without dropping denials: overflow collapses to a
262
+ // conservative account-wide restriction until the latest known reset.
263
+ let requestRestrictions = [...restrictions.values()];
264
+ const evidenceTime = requestRestrictions.reduce(
265
+ (value, item) => (item.observedAt > value ? item.observedAt : value),
266
+ observation.observedAt,
267
+ );
268
+ const liveDenials = requestRestrictions.filter(
269
+ (item) =>
270
+ item.status === "rejected" &&
271
+ (item.resetsAt ? Date.parse(item.resetsAt) : Date.parse(item.observedAt) + 60_000) >
272
+ Date.parse(evidenceTime),
273
+ );
274
+ if (requestRestrictions.length > 64 && liveDenials.length === 0) {
275
+ requestRestrictions = requestRestrictions
276
+ .sort((left, right) => right.observedAt.localeCompare(left.observedAt))
277
+ .slice(0, 64);
278
+ } else if (requestRestrictions.length > 64) {
279
+ const observedAt = evidenceTime;
280
+ const resetsAt = new Date(
281
+ Math.max(
282
+ ...liveDenials.map((item) =>
283
+ item.resetsAt ? Date.parse(item.resetsAt) : Date.parse(item.observedAt) + 60_000,
284
+ ),
285
+ Date.parse(observedAt) + 60_000,
286
+ ),
287
+ ).toISOString();
288
+ requestRestrictions = [
289
+ {
290
+ status: "rejected",
291
+ resetsAt,
292
+ representativeClaim: null,
293
+ overageStatus: null,
294
+ overageResetsAt: null,
295
+ upstreamModelId: null,
296
+ observedAt,
297
+ },
298
+ ];
299
+ }
300
+ const newest = !current.observedAt || current.observedAt < observation.observedAt;
301
+ const tied = current.observedAt === observation.observedAt;
302
+ let requestStatus = current.requestStatus ?? null;
303
+ if (newest) requestStatus = incoming ?? null;
304
+ else if (tied && JSON.stringify(requestStatus) !== JSON.stringify(incoming ?? null)) {
305
+ // Millisecond timestamps do not order concurrent responses. Never restore
306
+ // paid authority or erase a denial on an ambiguous tie.
307
+ requestStatus =
308
+ incoming && requestStatus && evidenceKey(incoming) === evidenceKey(requestStatus)
309
+ ? tiedRequest(requestStatus, incoming)
310
+ : null;
99
311
  }
100
- const newest = !current.observedAt || current.observedAt <= observation.observedAt;
101
312
  return {
102
313
  ...current,
314
+ requestRestrictions,
315
+ requestStatus,
103
316
  windows: ClaudeUsageWindowId.options.flatMap((id) =>
104
317
  windows.has(id) ? [windows.get(id)!] : [],
105
318
  ),
106
- ...(newest ? { observedAt: observation.observedAt, source: observation.source } : {}),
319
+ ...(newest
320
+ ? {
321
+ observedAt: observation.observedAt,
322
+ source: observation.source,
323
+ // A newer direct or partial observation cannot retain an older paid
324
+ // fallback authorization. Window readings remain independently merged.
325
+ }
326
+ : {}),
107
327
  };
108
328
  }