The best way to control Claude Code, Codex and more from any computer or phone
fix(server): proxied usage limits take their reset time from the CLIProxyAPI hub (#36238)
Julius Marminge committed
Nov 13, 2026 at 10:10 UTC
a09e54a3632c4b75c5b340de0a2c7fc34d46025d
13 files changed
+410
-25
apps/server/src/orchestration-v2/Orchestrator.ts
+16
-1
@@ -4455,7 +4455,22 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
4455
)
4456
.map((message) => message.id),
4457
);
4458
- if (queuedRuns.some((run) => !automaticMessageIds.has(run.userMessageId))) {
4458
+ const userRuns = queuedRuns.filter((run) => !automaticMessageIds.has(run.userMessageId));
4459
+ // User work waiting behind a usage limit cannot start until the reset or the user acts.
4460
+ const latest = latestExecutedRun(projection.runs);
4461
+ const limitRecords =
4462
+ userRuns.length === 0 || latest?.status !== "failed"
4463
+ ? null
4464
+ : yield* loadProjectionForCommand(command, ["turnItems", "providerSessions"], {
4465
+ turnItemTypes: ["error"],
4466
+ turnItemRunIds: [latest.id],
4467
+ });
4468
+ const heldBehindLimit =
4469
+ limitRecords !== null &&
4470
+ userRuns.every((run) =>
4471
+ usageLimitHoldsQueue({ ...limitRecords, runs: projection.runs }, run.providerInstanceId),
4472
+ );
4473
+ if (userRuns.length > 0 && !heldBehindLimit) {
4474
return yield* new OrchestratorDispatchError({
4475
commandId: command.commandId,
4476
commandType: command.type,
apps/server/src/orchestration-v2/ProviderEventIngestor.test.ts
+28
-4
@@ -49,8 +49,10 @@ import * as ProviderEventIngestor from "./ProviderEventIngestor.ts";
49
import * as ProviderUsageAnalytics from "../telemetry/ProviderUsageAnalytics.ts";
50
import * as ThreadCommandExecutor from "./ThreadCommandExecutor.ts";
51
import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
52
+import { UsageLimitResetFallback } from "../usage/UsageLimitSources.ts";
53
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
54
import type { ProviderInstance } from "@t3tools/provider-core/server/driver";
55
+import type { ServerProvider } from "@t3tools/contracts";
56
import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
57
import {
58
makeProviderEventRoutingState,
@@ -230,7 +232,7 @@ function threadCreatedEvent(
232
233
const layer = it.layer(layerTest);
234
233
-it.effect("refreshes the failing instance snapshot after a committed usage_limit terminal", () =>
235
+it.effect("takes a hub's reset for an unreset usage_limit, then refreshes the snapshot", () =>
236
Effect.gen(function* () {
237
const refreshed = yield* Deferred.make<void>();
238
const adapter = yield* ProviderAdapter.ProviderAdapterV2.pipe(
@@ -261,7 +263,9 @@ it.effect("refreshes the failing instance snapshot after a committed usage_limit
263
},
264
snapshot: {
265
refreshUsage: Deferred.succeed(refreshed, undefined).pipe(Effect.asVoid),
264
- getSnapshot: Effect.die("unused"),
266
+ getSnapshot: Effect.succeed({
267
+ auth: { status: "authenticated", endpoint: "http://hub.test:8317" },
268
+ } as ServerProvider),
269
refresh: Effect.die("unused"),
270
resolveMaintenance: () => Effect.die("unused"),
271
applyUsageLimits: () => Effect.die("unused"),
@@ -269,6 +273,7 @@ it.effect("refreshes the failing instance snapshot after a committed usage_limit
273
},
274
};
275
const lookups: ProviderInstanceId[] = [];
276
+ const hubLookups: Array<[string, string, string | null]> = [];
277
const instances = Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
278
getInstance: (id) =>
279
Effect.sync(() => {
@@ -317,10 +322,29 @@ it.effect("refreshes the failing instance snapshot after a committed usage_limit
322
});
323
assert.equal(stored.length, 1);
324
if (failureClass === "validation_error") assert.deepEqual(lookups, []);
325
+ else {
326
+ const event = stored[0]?.event;
327
+ assert.equal(
328
+ event?.type === "turn-item.updated" && event.payload.type === "error"
329
+ ? event.payload.failure.resetAt
330
+ : undefined,
331
+ "2026-11-13T18:00:00.000Z",
332
+ );
333
+ }
334
}
321
- assert.deepEqual(lookups, [instance.instanceId]);
335
+ assert.deepEqual(lookups, [instance.instanceId, instance.instanceId]);
336
+ assert.deepEqual(hubLookups, [["cursor", "http://hub.test:8317", "gpt-5.4"]]);
337
yield* Deferred.await(refreshed);
323
- }).pipe(Effect.provide(makeLayerTest(layerTestEventSink, instances)));
338
+ }).pipe(
339
+ Effect.provide(makeLayerTest(layerTestEventSink, instances)),
340
+ Effect.provideService(UsageLimitResetFallback, {
341
+ resetAt: (driver, endpoint, model) =>
342
+ Effect.sync(() => {
343
+ hubLookups.push([driver, endpoint, model]);
344
+ return "2026-11-13T18:00:00.000Z";
345
+ }),
346
+ }),
347
+ );
348
}),
349
);
350
apps/server/src/orchestration-v2/ProviderEventIngestor.ts
+33
-1
@@ -32,6 +32,7 @@ import {
32
} from "../telemetry/ProviderUsageAnalytics.ts";
33
import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
34
import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
35
+import { UsageLimitResetFallback } from "../usage/UsageLimitSources.ts";
36
import * as EventSink from "./EventSink.ts";
37
import * as ProjectionStore from "./ProjectionStore.ts";
38
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
@@ -254,6 +255,7 @@ export const layer: Layer.Layer<
255
const analytics = yield* ProviderTurnAnalytics;
256
const agentScope = yield* AgentScope;
257
const instances = yield* ProviderInstanceRegistry.ProviderInstanceRegistry;
258
+ const usageLimitResets = yield* UsageLimitResetFallback;
259
const scope = yield* Effect.scope;
260
const completedTurnAnalytics = new Set<string>();
261
@@ -656,9 +658,39 @@ export const layer: Layer.Layer<
658
return dismissed;
659
}
660
const occurredAt = yield* DateTime.now;
659
- const failure = (yield* agentScope.oomKilled(input.threadId))
661
+ const reported = (yield* agentScope.oomKilled(input.threadId))
662
? { ...input.event.failure, message: "Killed: out of memory.", code: "oom_kill" }
663
: input.event.failure;
664
+ // A proxied CLI can drop the reset time; the hub still knows when its pool refills.
665
+ const endpoint =
666
+ reported.class === "usage_limit" && reported.resetAt == null
667
+ ? (yield* Effect.flatMap(
668
+ instances.getInstance(input.providerInstanceId),
669
+ (instance) => instance?.snapshot.getSnapshot ?? Effect.undefined,
670
+ ))?.auth.endpoint
671
+ : undefined;
672
+ const hubResetAt =
673
+ endpoint === undefined
674
+ ? null
675
+ : yield* Effect.gen(function* () {
676
+ // The failing run's model, which may differ from a selection changed mid-turn.
677
+ const { runs } =
678
+ input.runId === undefined
679
+ ? { runs: [] }
680
+ : yield* projections.getThreadRecords(input.threadId, ["runs"], {
681
+ runIds: [input.runId],
682
+ });
683
+ return (
684
+ runs[0]?.modelSelection ??
685
+ (yield* projections.getThread(input.threadId)).modelSelection
686
+ ).model;
687
+ }).pipe(
688
+ Effect.orElseSucceed(() => null),
689
+ Effect.flatMap((model) =>
690
+ usageLimitResets.resetAt(input.event.driver, endpoint, model),
691
+ ),
692
+ );
693
+ const failure = hubResetAt === null ? reported : { ...reported, resetAt: hubResetAt };
694
return [
695
...dismissed,
696
yield* makeDomainEvent(input, {
apps/server/src/orchestration-v2/runtimeLayer.test.ts
+55
-7
@@ -9557,8 +9557,8 @@ it.layer(layerSharedApplicationDataPlaneTest)("pending provider interruption", (
9557
});
9558
9559
it.layer(layerTest)("snooze queued runs", (it) => {
9560
- it.effect.each(["notification", "delegated-completion", "user"] as const)(
9561
- "only user messages block snooze with a held %s run",
9560
+ it.effect.each(["notification", "delegated-completion", "user", "limited-user"] as const)(
9561
+ "only user messages block snooze with a queued %s run, unless a usage limit holds them",
9562
(kind) =>
9563
Effect.gen(function* () {
9564
const orchestrator = yield* Orchestrator.OrchestratorV2;
@@ -9627,8 +9627,8 @@ it.layer(layerTest)("snooze queued runs", (it) => {
9627
attachments: [],
9628
modelSelection,
9629
dispatchMode: { type: "queue_after_active" },
9630
- createdBy: kind === "user" ? "user" : "agent",
9631
- creationSource: kind === "user" ? "web" : "server",
9630
+ createdBy: kind === "user" || kind === "limited-user" ? "user" : "agent",
9631
+ creationSource: kind === "user" || kind === "limited-user" ? "web" : "server",
9632
...(kind === "notification"
9633
? {
9634
notification: {
@@ -9647,6 +9647,43 @@ it.layer(layerTest)("snooze queued runs", (it) => {
9647
}
9648
: {}),
9649
});
9650
+ if (kind === "limited-user") {
9651
+ yield* eventSink.write({
9652
+ events: [
9653
+ {
9654
+ id: EventId.make(`limited:${threadId}`),
9655
+ type: "turn-item.updated",
9656
+ threadId,
9657
+ occurredAt: now,
9658
+ payload: {
9659
+ id: TurnItemId.make(`limited:${threadId}`),
9660
+ type: "error",
9661
+ threadId,
9662
+ runId: activeRun.id,
9663
+ nodeId: activeRun.rootNodeId,
9664
+ providerThreadId: null,
9665
+ providerTurnId: null,
9666
+ nativeItemRef: null,
9667
+ parentItemId: null,
9668
+ ordinal: 2,
9669
+ status: "failed",
9670
+ title: "Usage limit reached",
9671
+ startedAt: now,
9672
+ completedAt: now,
9673
+ updatedAt: now,
9674
+ // A proxied provider can report no reset time.
9675
+ failure: {
9676
+ class: "usage_limit",
9677
+ message: "Claude API rate limit reached. Try again later.",
9678
+ code: "api_error_429",
9679
+ retryable: true,
9680
+ resetAt: null,
9681
+ },
9682
+ },
9683
+ },
9684
+ ],
9685
+ });
9686
+ }
9687
const beforeRecovery = yield* orchestrator.getThreadProjection(threadId);
9688
yield* eventSink.commitCommand({
9689
commandId: CommandId.make(`recovery:${threadId}`),
@@ -9661,13 +9698,24 @@ it.layer(layerTest)("snooze queued runs", (it) => {
9698
occurredAt: now,
9699
payload:
9700
run.status === "queued"
9664
- ? { ...run, queueHeld: true }
9665
- : { ...run, status: "cancelled" as const, completedAt: now },
9701
+ ? // A usage limit stops the queue from starting without marking it held.
9702
+ kind === "limited-user"
9703
+ ? run
9704
+ : { ...run, queueHeld: true }
9705
+ : {
9706
+ ...run,
9707
+ status: kind === "limited-user" ? ("failed" as const) : ("cancelled" as const),
9708
+ completedAt: now,
9709
+ },
9710
})),
9711
effects: [],
9712
});
9713
const beforeSnooze = yield* orchestrator.getThreadProjection(threadId);
9670
- assert.isTrue(beforeSnooze.runs.some((run) => run.status === "queued" && run.queueHeld));
9714
+ assert.isTrue(
9715
+ beforeSnooze.runs.some(
9716
+ (run) => run.status === "queued" && (kind === "limited-user" || run.queueHeld),
9717
+ ),
9718
+ );
9719
const snooze = orchestrator.dispatch({
9720
type: "thread.snooze",
9721
commandId: CommandId.make(`snooze:${threadId}`),
apps/server/src/provider/ClaudeProvider.ts
+4
-1
@@ -776,6 +776,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
776
(yield* readClaudeSettingsEnv(claudeSettings, cwd, resolvedEnvironment)).ANTHROPIC_BASE_URL ??
777
resolvedEnvironment.ANTHROPIC_BASE_URL;
778
const customApiEndpoint = customClaudeApiEndpointHost(baseUrl) !== undefined;
779
+ const endpoint = customApiEndpoint ? URL.parse(baseUrl?.trim() ?? "")?.origin : undefined;
780
if (!customApiEndpoint && claudeAuthStatus(capabilities) === "unauthenticated") {
781
const path = yield* Path.Path;
782
const configDir = (yield* makeClaudeEnvironment(claudeSettings, resolvedEnvironment))
@@ -804,7 +805,9 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
805
// A proxy's ANTHROPIC_AUTH_TOKEN reads as an API key; the endpoint is what the token is for.
806
const authMetadata =
807
apiProviderAuthMetadata(capabilities.apiProvider) ??
807
- (customApiEndpoint ? { type: "customEndpoint", label: "Custom API endpoint" } : undefined) ??
808
+ (customApiEndpoint
809
+ ? { type: "customEndpoint", label: "Custom API endpoint", ...(endpoint ? { endpoint } : {}) }
810
+ : undefined) ??
811
claudeAuthMetadata({
812
subscriptionType: capabilities.subscriptionType,
813
authMethod: capabilities.tokenSource,
apps/server/src/provider/CodexProvider.test.ts
+9
@@ -2,6 +2,7 @@ import { assert, it } from "@effect/vitest";
2
3
import {
4
applyPreferredCodexDefaultModel,
5
+ codexCustomEndpoint,
6
codexRoutesSpendNativeQuota,
7
mapCodexModelCapabilities,
8
} from "./CodexProvider.ts";
@@ -192,4 +193,12 @@ it("reports native quota only for an OpenAI login on a native route", () => {
193
name,
194
);
195
}
196
+ // The custom endpoint is what a usage-limit hub is matched against.
197
+ assert.strictEqual(codexCustomEndpoint(hub), "https://hub.example.com");
198
+ assert.strictEqual(
199
+ codexCustomEndpoint({ openai_base_url: "http://127.0.0.1:8317/v1" }),
200
+ "http://127.0.0.1:8317",
201
+ );
202
+ assert.strictEqual(codexCustomEndpoint({ openai_base_url: "https://chatgpt.com/x" }), undefined);
203
+ assert.strictEqual(codexCustomEndpoint({}), undefined);
204
});
apps/server/src/provider/CodexProvider.ts
+25
-8
@@ -94,17 +94,21 @@ const CodexCyberAccessConfig = Schema.Struct({
94
});
95
const decodeCodexCyberAccessConfig = Schema.decodeUnknownOption(CodexCyberAccessConfig);
96
97
-function routesToNativeOpenai(config: unknown): boolean {
97
+// Null is Codex's auth-dependent OpenAI default; undefined is a route that cannot be read.
98
+function codexRouteBaseUrl(config: unknown): string | null | undefined {
99
const decoded = decodeCodexRoutingConfig(config);
99
- if (Option.isNone(decoded)) return false;
100
+ if (Option.isNone(decoded)) return undefined;
101
const routing = decoded.value;
102
const providerId = routing.model_provider ?? "openai";
103
+ if (providerId === "openai") return routing.openai_base_url || null;
104
const provider = routing.model_providers?.[providerId];
103
- if (providerId !== "openai" && !provider) return false;
104
- const baseUrl =
105
- providerId === "openai" ? routing.openai_base_url || undefined : provider?.base_url;
106
- // A provider without an override uses Codex's auth-dependent OpenAI default.
107
- if (baseUrl == null) return true;
105
+ return provider ? (provider.base_url ?? null) : undefined;
106
+}
107
+
108
+function routesToNativeOpenai(config: unknown): boolean {
109
+ const baseUrl = codexRouteBaseUrl(config);
110
+ if (baseUrl === undefined) return false;
111
+ if (baseUrl === null) return true;
112
if (!URL.canParse(baseUrl)) return false;
113
const url = new URL(baseUrl);
114
return (
@@ -113,6 +117,15 @@ function routesToNativeOpenai(config: unknown): boolean {
117
);
118
}
119
120
+/** The origin of the custom endpoint Codex sends model requests to, if it uses one. */
121
+export function codexCustomEndpoint(config: unknown): string | undefined {
122
+ const baseUrl = codexRouteBaseUrl(config);
123
+ const url = baseUrl ? URL.parse(baseUrl) : null;
124
+ return url && /^https?:$/.test(url.protocol) && !routesToNativeOpenai(config)
125
+ ? url.origin
126
+ : undefined;
127
+}
128
+
129
// A stored login does not mean this provider's traffic spends that login's quota.
130
export const codexRoutesSpendNativeQuota = (
131
account: CodexSchema.V2GetAccountResponse,
@@ -140,6 +153,7 @@ const CODEX_PRESENTATION = {
153
154
export interface CodexAppServerProviderSnapshot {
155
readonly account: CodexSchema.V2GetAccountResponse;
156
+ readonly endpoint?: string | undefined;
157
readonly nativeUsage?: boolean;
158
readonly rateLimits?: CodexRateLimitsProbe;
159
readonly version: string | undefined;
@@ -757,6 +771,7 @@ const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(fun
771
const cyberAccess = Option.getOrUndefined(decodeCodexCyberAccessConfig(config));
772
return {
773
account: accountResponse,
774
+ endpoint: config ? codexCustomEndpoint(config) : undefined,
775
nativeUsage,
776
...(rateLimits ? { rateLimits } : {}),
777
version,
@@ -1075,7 +1090,9 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
1090
installed: true,
1091
version: snapshot.version ?? null,
1092
status: snapshot.models === undefined ? "warning" : accountStatus.status,
1078
- auth: accountStatus.auth,
1093
+ auth: snapshot.endpoint
1094
+ ? { ...accountStatus.auth, endpoint: snapshot.endpoint }
1095
+ : accountStatus.auth,
1096
...(accountStatus.message
1097
? { message: accountStatus.message }
1098
: snapshot.models === undefined
apps/server/src/provider/claudeUsageLimits.ts
+13
-1
@@ -47,8 +47,20 @@ export const makeClaudeScopedLimitNames = Ref.make<ClaudeScopedLimitNames>({
47
overageIncluded: undefined,
48
});
49
50
+const SCOPED_WINDOW_PREFIX = "seven_day_";
51
+const scopeToken = (name: string) => name.toLowerCase().replace(/[^a-z0-9]+/g, "_");
52
+
53
function scopedWindowId(displayName: string): string {
51
- return `seven_day_${displayName.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
54
+ return `${SCOPED_WINDOW_PREFIX}${scopeToken(displayName)}`;
55
+}
56
+
57
+/** A model-scoped weekly allowance blocks only its own model; an unknown model is not blocked. */
58
+export function windowLimitsModel(
59
+ window: Pick<ServerProviderUsageWindow, "id">,
60
+ model: string | null,
61
+): boolean {
62
+ if (!window.id.startsWith(SCOPED_WINDOW_PREFIX)) return true;
63
+ return model !== null && scopeToken(model).includes(window.id.slice(SCOPED_WINDOW_PREFIX.length));
64
}
65
66
function scopedWindow(
apps/server/src/server.ts
+1
@@ -574,6 +574,7 @@ const layerScheduledTaskWebhookOrigin = Layer.effect(
574
);
575
576
const layerOrchestrationV2Runtime = RuntimeLayer.layerProduction.pipe(
577
+ Layer.provide(UsageLimitSources.layerResetFallback),
578
Layer.provide(layerScheduledTaskWebhookOrigin),
579
Layer.provide(ProviderUsageAnalytics.layer),
580
Layer.provide(layerCheckpointStore),
apps/server/src/usage/UsageLimitSources.test.ts
+151
-1
@@ -1,11 +1,21 @@
1
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
2
import { expect, it } from "@effect/vitest";
3
-import { SecretProviderId, ServerConfigStreamEvent, UsageLimitSourceId } from "@t3tools/contracts";
3
+import {
4
+ ProviderDriverKind,
5
+ SecretProviderId,
6
+ ServerConfigStreamEvent,
7
+ UsageLimitSourceId,
8
+ type ServerProviderUsageWindow,
9
+ type UsageLimitSourceSnapshot,
10
+} from "@t3tools/contracts";
11
import * as SecretResolver from "@t3tools/secret-provider-core/server/SecretResolver";
12
+import * as DateTime from "effect/DateTime";
13
import * as Effect from "effect/Effect";
14
+import * as Fiber from "effect/Fiber";
15
import * as Layer from "effect/Layer";
16
import * as Schema from "effect/Schema";
17
import * as Stream from "effect/Stream";
18
+import * as TestClock from "effect/testing/TestClock";
19
import { HttpClient, HttpClientResponse } from "effect/http";
20
21
import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
@@ -26,6 +36,14 @@ it.effect("keeps malformed source URLs encodable for config subscribers", () =>
36
"hub.test:8317",
37
"Usage limit source",
38
]);
39
+ // Only an http(s) hub URL names an endpoint an agent can be sent to.
40
+ expect(snapshots.map((source) => source.origin)).toEqual([
41
+ undefined,
42
+ undefined,
43
+ undefined,
44
+ "https://hub.test:8317",
45
+ undefined,
46
+ ]);
47
expect(() =>
48
encodeConfigEvent({
49
version: 1,
@@ -155,3 +173,135 @@ it.effect("reads a management key from its secret provider", () => {
173
]),
174
);
175
});
176
+
177
+const NOW = Date.parse("2026-11-13T12:00:00.000Z");
178
+const at = (hours: number) => DateTime.formatIso(DateTime.makeUnsafe(NOW + hours * 3_600_000));
179
+const spent = (id: string, hours: number): ServerProviderUsageWindow => ({
180
+ id,
181
+ kind: "weekly",
182
+ label: id,
183
+ usedPercent: 100,
184
+ resetsAt: at(hours),
185
+});
186
+const hub = (
187
+ accounts: ReadonlyArray<{
188
+ driver?: string;
189
+ windows?: ReadonlyArray<ServerProviderUsageWindow>;
190
+ unavailable?: true;
191
+ }>,
192
+): UsageLimitSourceSnapshot => ({
193
+ id: UsageLimitSourceId.make("hub"),
194
+ kind: "cliproxy",
195
+ label: "hub",
196
+ checkedAt: at(0),
197
+ accounts: accounts.map((account, index) => ({
198
+ id: `account-${index}`,
199
+ driver: ProviderDriverKind.make(account.driver ?? "claudeAgent"),
200
+ usageLimits: {
201
+ checkedAt: at(0),
202
+ windows: account.windows ?? [],
203
+ ...(account.unavailable ? { unavailable: { reason: "probeFailed" as const } } : {}),
204
+ },
205
+ })),
206
+});
207
+
208
+it.each([
209
+ {
210
+ name: "earliest refill when every account is spent, each at its latest spent window",
211
+ accounts: [
212
+ { windows: [spent("five_hour", 1), spent("seven_day", 3)] },
213
+ { windows: [spent("five_hour", 2)] },
214
+ { driver: "codex", windows: [] },
215
+ ],
216
+ model: "claude-haiku-5-5",
217
+ expected: at(2),
218
+ },
219
+ {
220
+ name: "unknown while an account still has room",
221
+ accounts: [{ windows: [spent("five_hour", 1)] }, { windows: [] }],
222
+ model: "claude-haiku-5-5",
223
+ expected: null,
224
+ },
225
+ {
226
+ name: "unknown while an account could not be read",
227
+ accounts: [{ windows: [spent("five_hour", 1)] }, { unavailable: true as const }],
228
+ model: "claude-haiku-5-5",
229
+ expected: null,
230
+ },
231
+ {
232
+ name: "unknown when a spent window has no reset or already reset",
233
+ accounts: [{ windows: [{ ...spent("five_hour", 1), resetsAt: undefined }] }],
234
+ model: "claude-haiku-5-5",
235
+ expected: null,
236
+ },
237
+ {
238
+ name: "a model-scoped weekly window blocks only its own model",
239
+ accounts: [{ windows: [spent("seven_day_fable", 5)] }],
240
+ model: "claude-haiku-5-5",
241
+ expected: null,
242
+ },
243
+ {
244
+ name: "a model-scoped weekly window blocks its own model",
245
+ accounts: [{ windows: [spent("seven_day_fable", 5)] }],
246
+ model: "claude-fable-5-2",
247
+ expected: at(5),
248
+ },
249
+ {
250
+ name: "no account of the driver",
251
+ accounts: [{ driver: "codex", windows: [spent("five_hour", 1)] }],
252
+ model: "claude-haiku-5-5",
253
+ expected: null,
254
+ },
255
+])("hub pool reset: $name", ({ accounts, model, expected }) => {
256
+ expect(
257
+ UsageLimitSources.hubPoolResetAt(
258
+ [hub(accounts)],
259
+ ProviderDriverKind.make("claudeAgent"),
260
+ model,
261
+ NOW,
262
+ ),
263
+ ).toBe(expected);
264
+});
265
+
266
+it.effect("the reset fallback refreshes its hub, and a stalled hub cannot hold the failure", () =>
267
+ Effect.gen(function* () {
268
+ yield* TestClock.setTime(NOW);
269
+ const roomLeft = { ...hub([{ windows: [spent("five_hour", 2)] }]), origin: "http://hub.test" };
270
+ const cached = {
271
+ ...roomLeft,
272
+ accounts: roomLeft.accounts.map((account) => ({
273
+ ...account,
274
+ usageLimits: {
275
+ ...account.usageLimits,
276
+ windows: account.usageLimits.windows.map((window) => ({ ...window, usedPercent: 99 })),
277
+ },
278
+ })),
279
+ };
280
+ let current: ReadonlyArray<UsageLimitSourceSnapshot> = [cached];
281
+ let refresh: Effect.Effect<void> = Effect.sync(() => {
282
+ current = [roomLeft];
283
+ });
284
+ const lookup = UsageLimitSources.UsageLimitResetFallback.pipe(
285
+ Effect.flatMap((fallback) =>
286
+ fallback.resetAt(ProviderDriverKind.make("claudeAgent"), "http://hub.test", null),
287
+ ),
288
+ Effect.provide(
289
+ UsageLimitSources.layerResetFallback.pipe(
290
+ Layer.provide(
291
+ Layer.mock(UsageLimitSources.UsageLimitSources)({
292
+ current: Effect.sync(() => current),
293
+ refresh: Effect.suspend(() => refresh),
294
+ }),
295
+ ),
296
+ ),
297
+ ),
298
+ );
299
+ // The last poll saw room; the account was spent after it.
300
+ expect(yield* lookup).toBe(at(2));
301
+ current = [cached];
302
+ refresh = Effect.never;
303
+ const stalled = yield* Effect.forkChild(lookup);
304
+ yield* TestClock.adjust("5 seconds");
305
+ expect(yield* Fiber.join(stalled)).toBeNull();
306
+ }),
307
+);
apps/server/src/usage/UsageLimitSources.ts
+71
-1
@@ -3,6 +3,7 @@ import {
3
UsageLimitSourceError,
4
type UsageLimitSourceConsumeResetCreditInput,
5
type ProviderConsumeResetCreditResult,
6
+ type ProviderDriverKind,
7
type ServerSettings,
8
UsageLimitSourceConfig,
9
settingsSecretLiteral,
@@ -26,6 +27,7 @@ import * as SecretResolver from "@t3tools/secret-provider-core/server/SecretReso
27
import * as SecretResolverLayer from "../secrets/SecretResolver.ts";
28
import { resolveSettingsSecrets } from "../secrets/settingsSecretValue.ts";
29
import * as Settings from "../serverSettings.ts";
30
+import { windowLimitsModel } from "../provider/claudeUsageLimits.ts";
31
import { makeCliproxyApi } from "./cliproxyApi.ts";
32
33
export class UsageLimitSources extends Context.Service<
@@ -79,7 +81,14 @@ export const make = Effect.gen(function* () {
81
config: UsageLimitSourceConfig,
82
) {
83
const checkedAt = DateTime.formatIso(yield* DateTime.now);
82
- const base = { id, kind: config.kind, label: sourceLabel(id, config), checkedAt } as const;
84
+ const url = URL.parse(config.url);
85
+ const base = {
86
+ id,
87
+ kind: config.kind,
88
+ label: sourceLabel(id, config),
89
+ ...(url && /^https?:$/.test(url.protocol) ? { origin: url.origin } : {}),
90
+ checkedAt,
91
+ } as const;
92
const managementKey = yield* readManagementKey(config);
93
if (managementKey.length === 0) {
94
return { ...base, accounts: [], error: missingManagementKey(config) };
@@ -198,3 +207,64 @@ export const make = Effect.gen(function* () {
207
export const layer = Layer.effect(UsageLimitSources, make).pipe(
208
Layer.provide(SecretResolverLayer.layer),
209
);
210
+
211
+/** A hub answers with a usage limit only when every account it routes the driver to is spent. */
212
+export function hubPoolResetAt(
213
+ sources: ReadonlyArray<UsageLimitSourceSnapshot>,
214
+ driver: ProviderDriverKind,
215
+ model: string | null,
216
+ now: number,
217
+): string | null {
218
+ let earliest: number | null = null;
219
+ for (const source of sources) {
220
+ for (const account of source.accounts) {
221
+ if (account.driver !== driver) continue;
222
+ // An unread account may be the one still blocked, so its refill is unknown.
223
+ if (account.usageLimits.unavailable) return null;
224
+ const spent = account.usageLimits.windows.filter(
225
+ (window) => window.usedPercent >= 100 && windowLimitsModel(window, model),
226
+ );
227
+ if (spent.length === 0) return null;
228
+ const resets = spent.map((window) => Date.parse(window.resetsAt ?? ""));
229
+ if (resets.some((reset) => !Number.isFinite(reset))) return null;
230
+ const recoversAt = Math.max(...resets);
231
+ if (recoversAt <= now) return null;
232
+ earliest = earliest === null ? recoversAt : Math.min(earliest, recoversAt);
233
+ }
234
+ }
235
+ return earliest === null ? null : DateTime.formatIso(DateTime.makeUnsafe(earliest));
236
+}
237
+
238
+export class UsageLimitResetFallback extends Context.Reference<{
239
+ readonly resetAt: (
240
+ driver: ProviderDriverKind,
241
+ endpoint: string,
242
+ model: string | null,
243
+ ) => Effect.Effect<string | null>;
244
+}>("t3/usage/UsageLimitResetFallback", {
245
+ defaultValue: () => ({ resetAt: () => Effect.succeed(null) }),
246
+}) {}
247
+
248
+export const layerResetFallback = Layer.effect(
249
+ UsageLimitResetFallback,
250
+ Effect.gen(function* () {
251
+ const sources = yield* UsageLimitSources;
252
+ return {
253
+ resetAt: Effect.fn("UsageLimitResetFallback.resetAt")(function* (driver, endpoint, model) {
254
+ // Only the hub at the instance's endpoint serves its turns.
255
+ const atEndpoint = Effect.map(sources.current, (current) =>
256
+ current.filter((source) => source.origin === endpoint),
257
+ );
258
+ if ((yield* atEndpoint).length === 0) return null;
259
+ // The pool usually ran out after the last poll, so the cached accounts still show room.
260
+ yield* sources.refresh.pipe(Effect.timeout("5 seconds"), Effect.ignore);
261
+ return hubPoolResetAt(
262
+ yield* atEndpoint,
263
+ driver,
264
+ model,
265
+ DateTime.toEpochMillis(yield* DateTime.now),
266
+ );
267
+ }),
268
+ };
269
+ }),
270
+);
packages/contracts/src/providerUsageLimits.ts
+2
@@ -86,6 +86,8 @@ export const UsageLimitSourceSnapshot = Schema.Struct({
86
id: UsageLimitSourceId,
87
kind: Schema.Literal("cliproxy"),
88
label: TrimmedNonEmptyString,
89
+ /** Origin of the hub, which also serves the agents sent through it. */
90
+ origin: Schema.optional(TrimmedNonEmptyString),
91
checkedAt: IsoDateTime,
92
accounts: ForwardCompatibleArray(UsageLimitSourceAccount),
93
error: Schema.optional(TrimmedNonEmptyString),
packages/contracts/src/server.ts
+2
@@ -70,6 +70,8 @@ export const ServerProviderAuth = Schema.Struct({
70
subscriptionSharing: Schema.optional(Schema.Boolean),
71
profileId: Schema.optional(TrimmedNonEmptyString),
72
workspaceId: Schema.optional(TrimmedNonEmptyString),
73
+ /** Origin of the custom endpoint the instance sends its requests to. */
74
+ endpoint: Schema.optional(TrimmedNonEmptyString),
75
});
76
export type ServerProviderAuth = typeof ServerProviderAuth.Type;
77