The best way to control Claude Code, Codex and more from any computer or phone
fix(server,cursor,opencode): refresh provider usage when a turn hits its usage limit (#26234)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
maria committed
Oct 29, 2026 at 02:37 UTC
8298664e9e46ad8af2c8966cfb4c08a2a31898a4
13 files changed
+373
-8
apps/server/src/orchestration-v2/ProviderEventIngestor.test.ts
+108
-1
@@ -46,6 +46,9 @@ import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
46
import * as ProjectionStore from "./ProjectionStore.ts";
47
import * as ProviderEventIngestor from "./ProviderEventIngestor.ts";
48
import * as ThreadCommandExecutor from "./ThreadCommandExecutor.ts";
49
+import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
50
+import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
51
+import type { ProviderInstance } from "@t3tools/provider-core/server/driver";
52
import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
53
import {
54
makeProviderEventRoutingState,
@@ -68,8 +71,16 @@ const layerGit = GitVcsDriver.layer.pipe(
71
Layer.provideMerge(NodeServices.layer),
72
);
73
71
-const makeLayerTest = <E>(ingestorEventSink: Layer.Layer<EventSink.EventSinkV2, E>) =>
74
+const layerEmptyInstances = Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
75
+ // @effect-diagnostics-next-line effectSucceedWithVoid:off - Optional instances require undefined rather than void.
76
+ getInstance: () => Effect.succeed(undefined),
77
+});
78
+const makeLayerTest = <E>(
79
+ ingestorEventSink: Layer.Layer<EventSink.EventSinkV2, E>,
80
+ instances = layerEmptyInstances,
81
+) =>
82
Layer.mergeAll(
83
+ instances,
84
layerTestDatabase,
85
layerTestStores,
86
layerTestEventSink,
@@ -79,6 +90,7 @@ const makeLayerTest = <E>(ingestorEventSink: Layer.Layer<EventSink.EventSinkV2,
90
ProviderEventIngestor.layer.pipe(
91
Layer.provide(
92
Layer.mergeAll(
93
+ instances,
94
layerTestStores,
95
ingestorEventSink,
96
IdAllocator.layer,
@@ -217,6 +229,101 @@ function threadCreatedEvent(
229
230
const layer = it.layer(layerTest);
231
232
+it.effect("refreshes the failing instance snapshot after a committed usage_limit terminal", () =>
233
+ Effect.scoped(
234
+ Effect.gen(function* () {
235
+ const refreshed = yield* Deferred.make<void>();
236
+ const adapter = yield* ProviderAdapter.ProviderAdapterV2.pipe(
237
+ Effect.provide(
238
+ Layer.mock(ProviderAdapter.ProviderAdapterV2)({
239
+ instanceId: ProviderInstanceId.make("cursor-work"),
240
+ driver: ProviderDriverKind.make("cursor"),
241
+ }),
242
+ ),
243
+ );
244
+ const instance: ProviderInstance = {
245
+ instanceId: ProviderInstanceId.make("cursor-work"),
246
+ driverKind: ProviderDriverKind.make("cursor"),
247
+ continuationIdentity: {
248
+ driverKind: ProviderDriverKind.make("cursor"),
249
+ continuationKey: "work",
250
+ },
251
+ enabled: true,
252
+ displayName: undefined,
253
+ orchestrationAdapter: adapter,
254
+ textGeneration: {
255
+ generateBranchName: () => Effect.die("unused"),
256
+ generateCommitMessage: () => Effect.die("unused"),
257
+ generatePrContent: () => Effect.die("unused"),
258
+ generateThreadTitle: () => Effect.die("unused"),
259
+ generateReviewGuide: () => Effect.die("unused"),
260
+ },
261
+ snapshot: {
262
+ refreshUsage: Deferred.succeed(refreshed, undefined).pipe(Effect.asVoid),
263
+ getSnapshot: Effect.die("unused"),
264
+ refresh: Effect.die("unused"),
265
+ resolveMaintenance: () => Effect.die("unused"),
266
+ applyUsageLimits: () => Effect.die("unused"),
267
+ streamChanges: Stream.empty,
268
+ },
269
+ };
270
+ const lookups: ProviderInstanceId[] = [];
271
+ const instances = Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
272
+ getInstance: (id) =>
273
+ Effect.sync(() => {
274
+ lookups.push(id);
275
+ return id === instance.instanceId ? instance : undefined;
276
+ }),
277
+ });
278
+ yield* Effect.gen(function* () {
279
+ const now = yield* DateTime.now;
280
+ const eventSink = yield* EventSink.EventSinkV2;
281
+ const ingestor = yield* ProviderEventIngestor.ProviderEventIngestorV2;
282
+ const idAllocator = yield* IdAllocator.IdAllocatorV2;
283
+ const threadEvent = yield* threadCreatedEvent(now);
284
+ yield* eventSink.write({ events: [threadEvent] });
285
+ const input = {
286
+ providerSessionId: yield* idAllocator.allocate.providerSession({
287
+ providerInstanceId: instance.instanceId,
288
+ threadId: threadEvent.threadId,
289
+ }),
290
+ providerInstanceId: instance.instanceId,
291
+ threadId: threadEvent.threadId,
292
+ };
293
+ for (const failureClass of ["validation_error", "usage_limit"] as const) {
294
+ const stored = yield* ingestor.ingestNormalized({
295
+ ...input,
296
+ event: {
297
+ type: "turn.terminal",
298
+ driver: instance.driverKind,
299
+ providerThreadId: idAllocator.derive.providerThread({
300
+ driver: instance.driverKind,
301
+ nativeThreadId: "limited",
302
+ }),
303
+ providerTurnId: idAllocator.derive.providerTurn({
304
+ driver: instance.driverKind,
305
+ nativeTurnId: failureClass,
306
+ }),
307
+ runOrdinal: 1,
308
+ failureItemOrdinal: 1,
309
+ status: "failed",
310
+ failure: makeProviderFailure({
311
+ class: failureClass,
312
+ message: "Provider rejected turn.",
313
+ }),
314
+ threadDisposition: "reusable",
315
+ },
316
+ });
317
+ assert.equal(stored.length, 1);
318
+ if (failureClass === "validation_error") assert.deepEqual(lookups, []);
319
+ }
320
+ assert.deepEqual(lookups, [instance.instanceId]);
321
+ yield* Deferred.await(refreshed);
322
+ }).pipe(Effect.provide(makeLayerTest(layerTestEventSink, instances)));
323
+ }),
324
+ ),
325
+);
326
+
327
it.effect("records accepted billed turn usage once without billing the context window", () => {
328
const recorded: Array<Readonly<Record<string, unknown>>> = [];
329
const layerAnalytics = Layer.succeed(ProviderEventIngestor.ProviderTurnAnalytics, {
apps/server/src/orchestration-v2/ProviderEventIngestor.ts
+21
@@ -34,6 +34,7 @@ import { isTemporaryWorktreeBranch } from "@t3tools/shared/git";
34
import { getModelSelectionStringOptionValue, modelSelectionsEqual } from "@t3tools/shared/model";
35
import * as AnalyticsService from "../telemetry/AnalyticsService.ts";
36
import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
37
+import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
38
import * as EventSink from "./EventSink.ts";
39
import * as ProjectionStore from "./ProjectionStore.ts";
40
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
@@ -326,6 +327,7 @@ export const layer: Layer.Layer<
327
| IdAllocator.IdAllocatorV2
328
| ProjectionStore.ProjectionStoreV2
329
| ThreadCommandExecutor.ThreadCommandExecutor
330
+ | ProviderInstanceRegistry.ProviderInstanceRegistry
331
> = Layer.effect(
332
ProviderEventIngestorV2,
333
Effect.gen(function* () {
@@ -336,6 +338,8 @@ export const layer: Layer.Layer<
338
const threadCommands = yield* ThreadCommandExecutor.ThreadCommandExecutor;
339
const analytics = yield* ProviderTurnAnalytics;
340
const agentScope = yield* AgentScope;
341
+ const instances = yield* ProviderInstanceRegistry.ProviderInstanceRegistry;
342
+ const scope = yield* Effect.scope;
343
const completedTurnAnalytics = new Set<string>();
344
345
const makeDomainEvent =
@@ -794,6 +798,23 @@ export const layer: Layer.Layer<
798
},
799
(effect, input) =>
800
effect.pipe(
801
+ Effect.tap((storedEvents) =>
802
+ Effect.gen(function* () {
803
+ if (
804
+ storedEvents.length === 0 ||
805
+ input.event.type !== "turn.terminal" ||
806
+ input.event.status !== "failed" ||
807
+ input.event.failure.class !== "usage_limit"
808
+ )
809
+ return;
810
+ const instance = yield* instances.getInstance(input.providerInstanceId);
811
+ if (!instance?.snapshot.refreshUsage) return;
812
+ yield* instance.snapshot.refreshUsage.pipe(
813
+ Effect.ignoreCause({ log: true }),
814
+ Effect.forkIn(scope, { startImmediately: true }),
815
+ );
816
+ }),
817
+ ),
818
Effect.flatMap((storedEvents) =>
819
Effect.gen(function* () {
820
if (input.event.type !== "app_thread.created") return storedEvents;
apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
+5
@@ -47,6 +47,7 @@ import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
47
import * as ProjectionStore from "./ProjectionStore.ts";
48
import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts";
49
import * as ProviderEventIngestor from "./ProviderEventIngestor.ts";
50
+import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
51
import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
52
import * as ThreadCommandExecutor from "./ThreadCommandExecutor.ts";
53
import * as ProviderSessionManager from "./ProviderSessionManager.ts";
@@ -533,6 +534,10 @@ function layerTest(input: {
534
const layerProviderEventIngestorTest = ProviderEventIngestor.layer.pipe(
535
Layer.provide(
536
Layer.mergeAll(
537
+ Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
538
+ // @effect-diagnostics-next-line effectSucceedWithVoid:off - Optional instances require undefined rather than void.
539
+ getInstance: () => Effect.succeed(undefined),
540
+ }),
541
layerConfiguredEventSink,
542
IdAllocator.layer,
543
layerTestStores,
apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts
+5
@@ -40,6 +40,7 @@ import * as ProviderAuthService from "../../provider/ProviderAuthService.ts";
40
import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
41
import * as ProviderContinuationService from "../ProviderContinuationService.ts";
42
import * as ProviderEventIngestor from "../ProviderEventIngestor.ts";
43
+import * as ProviderInstanceRegistry from "../../provider/ProviderInstanceRegistry.ts";
44
import * as ProviderRuntimeRecoveryService from "../ProviderRuntimeRecoveryService.ts";
45
import * as ProviderSessionManager from "../ProviderSessionManager.ts";
46
import * as CommandOutputRecorder from "./CommandOutputRecorder.ts";
@@ -320,6 +321,10 @@ export function layerWithRegistry<Error>(
321
const layerProviderEventIngestorProvided = ProviderEventIngestor.layer.pipe(
322
Layer.provide(
323
Layer.mergeAll(
324
+ Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
325
+ // @effect-diagnostics-next-line effectSucceedWithVoid:off - Optional instances require undefined rather than void.
326
+ getInstance: () => Effect.succeed(undefined),
327
+ }),
328
layerStores,
329
layerEventSinkProvided,
330
IdAllocator.layer,
apps/server/src/provider/Drivers/ClaudeDriver.ts
+1
@@ -299,6 +299,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
299
Effect.map(stampIdentity),
300
),
301
checkProvider,
302
+ invalidateUsageCache: Cache.invalidateAll(capabilitiesProbeCache),
303
enrichSnapshot: ({ settings, snapshot, publishSnapshot }) =>
304
resolveMaintenance().pipe(
305
Effect.flatMap((maintenanceCapabilities) =>
packages/provider-core/src/server/managedProvider.test.ts
+111
@@ -6,6 +6,7 @@ import {
6
type ServerProvider,
7
} from "@t3tools/contracts";
8
import { createModelCapabilities } from "@t3tools/shared/model";
9
+import * as Cache from "effect/Cache";
10
import * as Deferred from "effect/Deferred";
11
import * as Effect from "effect/Effect";
12
import * as Fiber from "effect/Fiber";
@@ -138,6 +139,116 @@ const enrichedSnapshotSecond: ServerProvider = {
139
};
140
141
describe("makeManagedServerProvider", () => {
142
+ it.effect("invalidates cached usage and queues one refresh behind an in-flight refresh", () =>
143
+ Effect.scoped(
144
+ Effect.gen(function* () {
145
+ const calls = yield* Ref.make(0);
146
+ const probeStarted = yield* Deferred.make<void>();
147
+ const releaseProbe = yield* Deferred.make<void>();
148
+ const cache = yield* Cache.makeWith(
149
+ () =>
150
+ Effect.gen(function* () {
151
+ const count = yield* Ref.updateAndGet(calls, (count) => count + 1);
152
+ if (count === 2) {
153
+ yield* Deferred.succeed(probeStarted, undefined);
154
+ yield* Deferred.await(releaseProbe);
155
+ }
156
+ return {
157
+ ...refreshedSnapshot,
158
+ usageLimits: {
159
+ checkedAt: refreshedSnapshot.checkedAt,
160
+ windows: [
161
+ {
162
+ id: "five_hour",
163
+ kind: "session",
164
+ label: "Session",
165
+ usedPercent: count === 1 ? 20 : 100,
166
+ },
167
+ ],
168
+ },
169
+ } satisfies ServerProvider;
170
+ }),
171
+ { capacity: 1, timeToLive: () => "5 minutes" },
172
+ );
173
+ const warmed = yield* Cache.get(cache, "claude");
174
+ const provider = yield* makeManagedServerProvider<TestSettings>({
175
+ resolveMaintenance: () => Effect.die("usage refresh must not resolve maintenance"),
176
+ getSettings: Effect.succeed({ enabled: true }),
177
+ streamSettings: Stream.empty,
178
+ haveSettingsChanged: () => false,
179
+ initialSnapshot: () => Effect.succeed(warmed),
180
+ checkProvider: Cache.get(cache, "claude"),
181
+ invalidateUsageCache: Cache.invalidateAll(cache),
182
+ refreshOnInterval: false,
183
+ });
184
+ yield* provider.streamChanges.pipe(Stream.take(1), Stream.runDrain);
185
+ assert.strictEqual(yield* Ref.get(calls), 1);
186
+ const refresh = yield* provider.refreshUsage!.pipe(Effect.forkChild);
187
+ yield* Deferred.await(probeStarted);
188
+ const queued = yield* provider.refreshUsage!.pipe(
189
+ Effect.forkChild({ startImmediately: true }),
190
+ );
191
+ yield* provider.refreshUsage!;
192
+ assert.strictEqual(yield* Ref.get(calls), 2);
193
+ assert.strictEqual((yield* provider.getSnapshot).usageLimits?.windows[0]?.usedPercent, 20);
194
+ yield* Deferred.succeed(releaseProbe, undefined);
195
+ yield* Fiber.join(refresh);
196
+ yield* Fiber.join(queued);
197
+ assert.strictEqual(yield* Ref.get(calls), 3);
198
+ assert.strictEqual((yield* provider.getSnapshot).usageLimits?.windows[0]?.usedPercent, 100);
199
+ }),
200
+ ).pipe(Effect.provide(layerAlwaysRunTest)),
201
+ );
202
+ it.effect("keeps the waiting usage refresh's claim when the running one is interrupted", () =>
203
+ Effect.scoped(
204
+ Effect.gen(function* () {
205
+ const calls = yield* Ref.make(0);
206
+ const usageProbeStarted = yield* Deferred.make<void>();
207
+ const statusProbeStarted = yield* Deferred.make<void>();
208
+ const releaseStatusProbe = yield* Deferred.make<void>();
209
+ const provider = yield* makeManagedServerProvider<TestSettings>({
210
+ resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
211
+ getSettings: Effect.succeed({ enabled: true }),
212
+ streamSettings: Stream.empty,
213
+ haveSettingsChanged: () => false,
214
+ initialSnapshot: () => Effect.succeed(initialSnapshot),
215
+ checkProvider: Effect.gen(function* () {
216
+ const count = yield* Ref.updateAndGet(calls, (count) => count + 1);
217
+ if (count === 2) {
218
+ yield* Deferred.succeed(usageProbeStarted, undefined);
219
+ return yield* Effect.never;
220
+ }
221
+ if (count === 3) {
222
+ yield* Deferred.succeed(statusProbeStarted, undefined);
223
+ yield* Deferred.await(releaseStatusProbe);
224
+ }
225
+ return {
226
+ ...refreshedSnapshot,
227
+ usageLimits: { checkedAt: refreshedSnapshot.checkedAt, windows: [] },
228
+ } satisfies ServerProvider;
229
+ }),
230
+ refreshOnInterval: false,
231
+ });
232
+ yield* provider.streamChanges.pipe(Stream.take(1), Stream.runDrain);
233
+ const running = yield* provider.refreshUsage!.pipe(Effect.forkChild);
234
+ yield* Deferred.await(usageProbeStarted);
235
+ const status = yield* provider.refresh.pipe(Effect.forkChild({ startImmediately: true }));
236
+ const waiting = yield* provider.refreshUsage!.pipe(
237
+ Effect.forkChild({ startImmediately: true }),
238
+ );
239
+ yield* Fiber.interrupt(running);
240
+ yield* Deferred.await(statusProbeStarted);
241
+ const extra = yield* provider.refreshUsage!.pipe(
242
+ Effect.forkChild({ startImmediately: true }),
243
+ );
244
+ yield* Deferred.succeed(releaseStatusProbe, undefined);
245
+ yield* Fiber.join(status);
246
+ yield* Fiber.join(waiting);
247
+ yield* Fiber.join(extra);
248
+ assert.strictEqual(yield* Ref.get(calls), 4);
249
+ }),
250
+ ).pipe(Effect.provide(layerAlwaysRunTest)),
251
+ );
252
it.effect(
253
"runs the initial provider check in the background and streams the refreshed snapshot",
254
() =>
packages/provider-core/src/server/managedProvider.ts
+35
@@ -44,6 +44,7 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
44
readonly haveSettingsChanged: (previous: Settings, next: Settings) => boolean;
45
readonly initialSnapshot: (settings: Settings) => Effect.Effect<ServerProvider>;
46
readonly checkProvider: Effect.Effect<ServerProvider, ServerSettingsError>;
47
+ readonly invalidateUsageCache?: Effect.Effect<void>;
48
readonly enrichSnapshot?: (input: {
49
readonly settings: Settings;
50
readonly snapshot: ServerProvider;
@@ -60,6 +61,7 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
61
> {
62
const host = yield* ProviderHost.ProviderHost;
63
const refreshSemaphore = yield* Semaphore.make(1);
64
+ const usageRefreshQueued = yield* Ref.make<symbol | null>(null);
65
const changesPubSub = yield* Effect.acquireRelease(
66
PubSub.unbounded<ServerProvider>(),
67
PubSub.shutdown,
@@ -216,6 +218,38 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
218
return yield* applySnapshot(nextSettings, { forceRefresh: true });
219
});
220
221
+ const refreshUsage = Effect.fn("ManagedServerProvider.refreshUsage")(function* () {
222
+ const { snapshot } = yield* Ref.get(snapshotStateRef);
223
+ if (
224
+ !snapshot.enabled ||
225
+ !snapshot.usageLimits ||
226
+ snapshot.usageLimits.unavailable?.reason === "unsupported"
227
+ )
228
+ return;
229
+ // An in-flight refresh may have read cached usage, so one refresh waits behind it.
230
+ const claim = Symbol();
231
+ const release = Ref.update(usageRefreshQueued, (queued) => (queued === claim ? null : queued));
232
+ yield* Effect.uninterruptibleMask((restore) =>
233
+ Ref.modify(usageRefreshQueued, (queued) => [queued !== null, queued ?? claim]).pipe(
234
+ Effect.flatMap((held) =>
235
+ held
236
+ ? Effect.void
237
+ : restore(
238
+ refreshSemaphore.withPermits(1)(
239
+ release.pipe(
240
+ Effect.andThen(input.invalidateUsageCache ?? Effect.void),
241
+ Effect.andThen(input.getSettings),
242
+ Effect.flatMap((settings) =>
243
+ applySnapshotBase(settings, { forceRefresh: true }),
244
+ ),
245
+ ),
246
+ ),
247
+ ).pipe(Effect.onInterrupt(() => release)),
248
+ ),
249
+ ),
250
+ );
251
+ });
252
+
253
const shouldRefreshOnInterval = Effect.gen(function* () {
254
const state = yield* Ref.get(snapshotStateRef);
255
// A disabled instance has nothing to probe; a periodic check would only
@@ -304,6 +338,7 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
338
.resolveMaintenance({ fresh: true })
339
.pipe(Effect.andThen(refreshSnapshot), Effect.tapError(Effect.logError), Effect.orDie),
340
applyUsageLimits,
341
+ refreshUsage: refreshUsage(),
342
get streamChanges() {
343
return Stream.fromPubSub(changesPubSub);
344
},
packages/provider-core/src/server/snapshot.ts
+6
-1
@@ -1,4 +1,8 @@
1
-import type { ProviderUsageLimitsUpdate, ServerProvider } from "@t3tools/contracts";
1
+import type {
2
+ ProviderUsageLimitsUpdate,
3
+ ServerProvider,
4
+ ServerSettingsError,
5
+} from "@t3tools/contracts";
6
import type * as Effect from "effect/Effect";
7
import type * as Stream from "effect/Stream";
8
import type { ProviderMaintenanceCapabilities } from "./maintenance.ts";
@@ -10,6 +14,7 @@ export interface ManagedServerProvider {
14
}) => Effect.Effect<ProviderMaintenanceCapabilities>;
15
readonly getSnapshot: Effect.Effect<ServerProvider>;
16
readonly refresh: Effect.Effect<ServerProvider>;
17
+ readonly refreshUsage?: Effect.Effect<void, ServerSettingsError>;
18
readonly streamChanges: Stream.Stream<ServerProvider>;
19
/** Merge windows by ID; updates with no usable window leave the snapshot untouched. */
20
readonly applyUsageLimits: (
packages/provider-cursor/src/server/CursorAgentSdk.ts
+15
@@ -43,6 +43,21 @@ export function cursorSdkFailureMessage(error: CursorAgentSdkRunnerError): strin
43
: `Cursor Agent SDK ${error.method} failed: ${reason}`;
44
}
45
46
+// The SDK maps backend details to codes like PRO_USER_USAGE_LIMIT or RATE_LIMITED, without a status.
47
+const CURSOR_USAGE_LIMIT_CODE =
48
+ /^(?:resource_exhausted|rate_limited(?:_changeable)?|\w*_usage_limit|\w*_rate_limit(?:_exceeded)?)$/i;
49
+
50
+export function isCursorUsageLimitError(cause: unknown): boolean {
51
+ const error = isCursorAgentSdkRunnerError(cause) ? cause.cause : cause;
52
+ if (typeof error !== "object" || error === null) return false;
53
+ const code = Reflect.get(error, "code");
54
+ return (
55
+ Reflect.get(error, "name") === "RateLimitError" ||
56
+ Reflect.get(error, "status") === 429 ||
57
+ (typeof code === "string" && CURSOR_USAGE_LIMIT_CODE.test(code))
58
+ );
59
+}
60
+
61
const GENERIC_SDK_ERROR_CODES = new Set(["", "error", "unknown"]);
62
63
function sdkErrorReason(cause: unknown): string | undefined {
packages/provider-cursor/src/server/adapter.test.ts
+11
-2
@@ -214,6 +214,15 @@ describe("CursorAdapterV2", () => {
214
);
215
216
it.effect.each([
217
+ {
218
+ reason: "the SDK's detailed plan usage limit code",
219
+ wait: Effect.succeed({
220
+ id: "native-cursor-run",
221
+ status: "error" as const,
222
+ error: { message: "You've hit your usage limit", code: "PRO_USER_USAGE_LIMIT" },
223
+ }),
224
+ failure: { class: "usage_limit", message: "You've hit your usage limit" },
225
+ },
226
{
227
reason: "the error Cursor's run ended with",
228
wait: Effect.succeed({
@@ -232,7 +241,7 @@ describe("CursorAdapterV2", () => {
241
},
242
},
243
{
235
- reason: "the SDK error that broke the run",
244
+ reason: "the SDK rate limit that broke the run",
245
wait: Effect.fail(
246
new CursorAgentSdk.CursorAgentSdkRunnerError({
247
method: "run.wait",
@@ -243,7 +252,7 @@ describe("CursorAdapterV2", () => {
252
}),
253
),
254
failure: {
246
- class: "transport_error",
255
+ class: "usage_limit",
256
message:
257
"Cursor Agent SDK run.wait failed: Too many requests (resource_exhausted, HTTP 429)",
258
},
packages/provider-cursor/src/server/adapter.ts
+6
-2
@@ -2506,7 +2506,9 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2506
cause: result.error,
2507
// makeProviderFailure never reads a cause's own text.
2508
message: result.error?.message,
2509
- class: "provider_error",
2509
+ class: CursorAgentSdk.isCursorUsageLimitError(result.error)
2510
+ ? "usage_limit"
2511
+ : "provider_error",
2512
})
2513
: makeProviderFailure({
2514
cause: transportFailure,
@@ -2532,7 +2534,9 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2534
message: CursorAgentSdk.isCursorAgentSdkRunnerError(cause)
2535
? CursorAgentSdk.cursorSdkFailureMessage(cause)
2536
: undefined,
2535
- class: "transport_error",
2537
+ class: CursorAgentSdk.isCursorUsageLimitError(cause)
2538
+ ? "usage_limit"
2539
+ : "transport_error",
2540
}),
2541
}),
2542
});
packages/provider-opencode/src/server/adapter.test.ts
+45
@@ -240,6 +240,51 @@ const makeOpenCodeRuntimeHarness = Effect.fn("makeOpenCodeRuntimeHarness")(funct
240
});
241
242
describe("OpenCodeAdapterV2", () => {
243
+ it.effect("classifies APIError 429 as a usage limit", () =>
244
+ Effect.gen(function* () {
245
+ const nativeEvents = asyncEventStream();
246
+ const harness = yield* makeOpenCodeRuntimeHarness("usage-limit", "root", {
247
+ event: { subscribe: async () => ({ stream: nativeEvents.stream }) },
248
+ session: {
249
+ create: async () => ({ data: { id: "root", time: { created: 1, updated: 1 } } }),
250
+ promptAsync: async () => ({ data: true }),
251
+ abort: async () => ({ data: true }),
252
+ children: async () => ({ data: [] }),
253
+ },
254
+ });
255
+ yield* harness.startTurn();
256
+ const received = yield* harness.runtime.events.pipe(
257
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
258
+ Stream.runCollect,
259
+ Effect.forkScoped,
260
+ );
261
+ yield* Effect.promise(() =>
262
+ nativeEvents.push({
263
+ type: "session.error",
264
+ properties: {
265
+ sessionID: "root",
266
+ error: {
267
+ name: "APIError",
268
+ data: {
269
+ message: "Provider rejected request",
270
+ statusCode: 429,
271
+ isRetryable: true,
272
+ },
273
+ },
274
+ },
275
+ }),
276
+ );
277
+ const terminal = (yield* Fiber.join(received)).find(
278
+ (event) => event.type === "turn.terminal",
279
+ );
280
+ assert.equal(terminal?.status, "failed");
281
+ assert.equal(terminal?.failure?.class, "usage_limit");
282
+ }).pipe(
283
+ Effect.provide(Layer.merge(IdAllocator.layer, McpProviderSessions.layer)),
284
+ Effect.scoped,
285
+ ),
286
+ );
287
+
288
it.effect("applies a changed runtime policy to the session on resume and turn start", () =>
289
Effect.gen(function* () {
290
const updates: Array<{ sessionID: string; permission: unknown }> = [];
packages/provider-opencode/src/server/adapter.ts
+4
-2
@@ -2643,6 +2643,8 @@ export const makeOpenCodeAdapterV2 = Effect.fn("makeOpenCodeAdapterV2")(function
2643
(state): state is OpenCodeThreadState => state !== undefined,
2644
);
2645
const message = openCodeErrorMessage(event);
2646
+ const error = event.properties.error;
2647
+ const usageLimit = error?.name === "APIError" && error.data.statusCode === 429;
2648
if (
2649
!isMessageAbortedError(event) &&
2650
(event.properties.sessionID === undefined ||
@@ -2659,8 +2661,8 @@ export const makeOpenCodeAdapterV2 = Effect.fn("makeOpenCodeAdapterV2")(function
2661
{
2662
failure: makeProviderFailure({
2663
message,
2662
- code: event.properties.error?.name ?? null,
2663
- class: "provider_error",
2664
+ code: error?.name ?? null,
2665
+ class: usageLimit ? "usage_limit" : "provider_error",
2666
}),
2667
threadDisposition:
2668
event.properties.sessionID === undefined ? "broken" : "reusable",