Skip to content

Commit ac7093c

Browse files
vitalyiegorovclaude
andcommitted
fix(codex): treat usage-limit stops as quota, not errors
Codex classifies plan limits, Business workspace credits, and spend caps alike as usageLimitExceeded. The adapter turned that into a runtime.error and a failed turn, so the thread went red with a generic error banner as if the provider had crashed. At the adapter boundary, a usage-limit stop now surfaces as a warning row carrying Codex's own sentence (reset time or workspace owner), and the turn it ends is cancelled rather than failed. Other errors are unchanged. Built with Claude Fable 5 in Claude Code. Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 18062da commit ac7093c

3 files changed

Lines changed: 210 additions & 2 deletions

File tree

‎apps/server/src/provider/Layers/CodexAdapter.test.ts‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -970,6 +970,175 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
970970
}),
971971
);
972972

973+
const usageLimitErrorCases = [
974+
["plan-limit", "You've hit your usage limit. Your limit will reset at 6:00 PM."],
975+
[
976+
"workspace-credits",
977+
"Your workspace is out of credits. Ask your workspace owner to refill in order to continue.",
978+
],
979+
] as const;
980+
981+
for (const [label, message] of usageLimitErrorCases) {
982+
it.effect(
983+
`maps a ${label} usage-limit error to runtime.warning with the provider message`,
984+
() =>
985+
Effect.gen(function* () {
986+
const { adapter, runtime } = yield* startLifecycleRuntime();
987+
const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(
988+
Effect.forkChild,
989+
);
990+
991+
yield* runtime.emit({
992+
id: asEventId(`evt-usage-limit-${label}`),
993+
kind: "notification",
994+
provider: ProviderDriverKind.make("codex"),
995+
threadId: asThreadId("thread-1"),
996+
createdAt: "2026-01-01T00:00:00.000Z",
997+
method: "error",
998+
turnId: asTurnId("turn-1"),
999+
payload: {
1000+
threadId: "thread-1",
1001+
turnId: "turn-1",
1002+
error: { message, codexErrorInfo: "usageLimitExceeded" },
1003+
willRetry: false,
1004+
},
1005+
} satisfies ProviderEvent);
1006+
1007+
const firstEvent = yield* Fiber.join(firstEventFiber);
1008+
1009+
NodeAssert.equal(firstEvent._tag, "Some");
1010+
if (firstEvent._tag !== "Some") {
1011+
return;
1012+
}
1013+
NodeAssert.equal(firstEvent.value.type, "runtime.warning");
1014+
if (firstEvent.value.type !== "runtime.warning") {
1015+
return;
1016+
}
1017+
NodeAssert.equal(firstEvent.value.turnId, "turn-1");
1018+
NodeAssert.equal(firstEvent.value.payload.message, message);
1019+
}),
1020+
);
1021+
}
1022+
1023+
it.effect("keeps non-usage-limit Codex error notifications as runtime.error", () =>
1024+
Effect.gen(function* () {
1025+
const { adapter, runtime } = yield* startLifecycleRuntime();
1026+
const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
1027+
1028+
yield* runtime.emit({
1029+
id: asEventId("evt-provider-error"),
1030+
kind: "notification",
1031+
provider: ProviderDriverKind.make("codex"),
1032+
threadId: asThreadId("thread-1"),
1033+
createdAt: "2026-01-01T00:00:00.000Z",
1034+
method: "error",
1035+
turnId: asTurnId("turn-1"),
1036+
payload: {
1037+
threadId: "thread-1",
1038+
turnId: "turn-1",
1039+
error: { message: "Stream disconnected", codexErrorInfo: "internalServerError" },
1040+
willRetry: false,
1041+
},
1042+
} satisfies ProviderEvent);
1043+
1044+
const firstEvent = yield* Fiber.join(firstEventFiber);
1045+
1046+
NodeAssert.equal(firstEvent._tag, "Some");
1047+
if (firstEvent._tag !== "Some") {
1048+
return;
1049+
}
1050+
NodeAssert.equal(firstEvent.value.type, "runtime.error");
1051+
if (firstEvent.value.type !== "runtime.error") {
1052+
return;
1053+
}
1054+
NodeAssert.equal(firstEvent.value.payload.class, "provider_error");
1055+
NodeAssert.equal(firstEvent.value.payload.message, "Stream disconnected");
1056+
}),
1057+
);
1058+
1059+
it.effect("ends a usage-limited turn as cancelled without an error message", () =>
1060+
Effect.gen(function* () {
1061+
const { adapter, runtime } = yield* startLifecycleRuntime();
1062+
const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
1063+
1064+
yield* runtime.emit({
1065+
id: asEventId("evt-usage-limit-turn-completed"),
1066+
kind: "notification",
1067+
provider: ProviderDriverKind.make("codex"),
1068+
threadId: asThreadId("thread-1"),
1069+
createdAt: "2026-01-01T00:00:00.000Z",
1070+
method: "turn/completed",
1071+
turnId: asTurnId("turn-1"),
1072+
payload: {
1073+
threadId: "thread-1",
1074+
turn: {
1075+
id: "turn-1",
1076+
status: "failed",
1077+
items: [],
1078+
error: {
1079+
message:
1080+
"Your workspace is out of credits. Ask your workspace owner to refill in order to continue.",
1081+
codexErrorInfo: "usageLimitExceeded",
1082+
},
1083+
},
1084+
},
1085+
} satisfies ProviderEvent);
1086+
1087+
const firstEvent = yield* Fiber.join(firstEventFiber);
1088+
1089+
NodeAssert.equal(firstEvent._tag, "Some");
1090+
if (firstEvent._tag !== "Some") {
1091+
return;
1092+
}
1093+
NodeAssert.equal(firstEvent.value.type, "turn.completed");
1094+
if (firstEvent.value.type !== "turn.completed") {
1095+
return;
1096+
}
1097+
NodeAssert.equal(firstEvent.value.turnId, "turn-1");
1098+
NodeAssert.equal(firstEvent.value.payload.state, "cancelled");
1099+
NodeAssert.equal(firstEvent.value.payload.errorMessage, undefined);
1100+
}),
1101+
);
1102+
1103+
it.effect("keeps other failed turns failed with their error message", () =>
1104+
Effect.gen(function* () {
1105+
const { adapter, runtime } = yield* startLifecycleRuntime();
1106+
const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
1107+
1108+
yield* runtime.emit({
1109+
id: asEventId("evt-failed-turn-completed"),
1110+
kind: "notification",
1111+
provider: ProviderDriverKind.make("codex"),
1112+
threadId: asThreadId("thread-1"),
1113+
createdAt: "2026-01-01T00:00:00.000Z",
1114+
method: "turn/completed",
1115+
turnId: asTurnId("turn-1"),
1116+
payload: {
1117+
threadId: "thread-1",
1118+
turn: {
1119+
id: "turn-1",
1120+
status: "failed",
1121+
items: [],
1122+
error: { message: "Stream disconnected", codexErrorInfo: "internalServerError" },
1123+
},
1124+
},
1125+
} satisfies ProviderEvent);
1126+
1127+
const firstEvent = yield* Fiber.join(firstEventFiber);
1128+
1129+
NodeAssert.equal(firstEvent._tag, "Some");
1130+
if (firstEvent._tag !== "Some") {
1131+
return;
1132+
}
1133+
NodeAssert.equal(firstEvent.value.type, "turn.completed");
1134+
if (firstEvent.value.type !== "turn.completed") {
1135+
return;
1136+
}
1137+
NodeAssert.equal(firstEvent.value.payload.state, "failed");
1138+
NodeAssert.equal(firstEvent.value.payload.errorMessage, "Stream disconnected");
1139+
}),
1140+
);
1141+
9731142
it.effect("maps retryable Codex error notifications to runtime.warning", () =>
9741143
Effect.gen(function* () {
9751144
const { adapter, runtime } = yield* startLifecycleRuntime();

‎apps/server/src/provider/Layers/CodexAdapter.ts‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,19 @@ function normalizeCodexTokenUsage(
193193
};
194194
}
195195

196+
/**
197+
* Codex reports plan windows, Business workspace credits, and spend caps alike
198+
* as `usageLimitExceeded`: the account is out of quota, nothing malfunctioned.
199+
* Such a stop surfaces as a warning row carrying Codex's own sentence (which
200+
* names the reset time or the workspace owner), and the turn it ends is
201+
* cancelled rather than failed, so the thread never turns red over quota.
202+
*/
203+
function isCodexUsageLimitError(
204+
error: { readonly codexErrorInfo?: unknown } | null | undefined,
205+
): boolean {
206+
return error?.codexErrorInfo === "usageLimitExceeded";
207+
}
208+
196209
function toTurnStatus(
197210
value: EffectCodexSchema.V2TurnCompletedNotification["turn"]["status"] | "cancelled",
198211
): "completed" | "failed" | "cancelled" | "interrupted" {
@@ -1061,13 +1074,15 @@ function mapToRuntimeEvents(
10611074
if (!payload) {
10621075
return [];
10631076
}
1064-
const errorMessage = trimText(payload.turn.error?.message);
1077+
// The usage-limit warning row already told the user why the turn ended.
1078+
const usageLimited = isCodexUsageLimitError(payload.turn.error);
1079+
const errorMessage = usageLimited ? undefined : trimText(payload.turn.error?.message);
10651080
return [
10661081
{
10671082
...runtimeEventBase(event, canonicalThreadId),
10681083
type: "turn.completed",
10691084
payload: {
1070-
state: toTurnStatus(payload.turn.status),
1085+
state: usageLimited ? "cancelled" : toTurnStatus(payload.turn.status),
10711086
...(errorMessage ? { errorMessage } : {}),
10721087
},
10731088
},
@@ -1540,6 +1555,18 @@ function mapToRuntimeEvents(
15401555
const payload = readPayload(EffectCodexSchema.V2ErrorNotification, event.payload);
15411556
const message = payload?.error.message ?? event.message ?? "Provider runtime error";
15421557
const willRetry = payload?.willRetry === true;
1558+
if (isCodexUsageLimitError(payload?.error)) {
1559+
return [
1560+
{
1561+
type: "runtime.warning",
1562+
...runtimeEventBase(event, canonicalThreadId),
1563+
payload: {
1564+
message,
1565+
...(event.payload !== undefined ? { detail: event.payload } : {}),
1566+
},
1567+
},
1568+
];
1569+
}
15431570
return [
15441571
{
15451572
type: willRetry ? "runtime.warning" : "runtime.error",

‎docs/user/providers-codex.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,18 @@ Log in with Codex normally:
2828
codex login
2929
```
3030

31+
## Codex Says I Hit A Limit Or My Workspace Is Out Of Credits
32+
33+
When Codex refuses a turn because the account is out of quota, the thread shows a warning line
34+
with Codex's own message and the turn ends. Nothing broke, so the thread does not show an error.
35+
36+
What the message means depends on the account:
37+
38+
- On a personal plan, it names when the limit resets. Wait for the reset, or switch to another
39+
Codex account for the next turn.
40+
- On a Business or Enterprise workspace, it says the workspace is out of credits or hit its spend
41+
cap. Ask the workspace owner to add credits or raise the cap, then send your message again.
42+
3143
## Send feedback to OpenAI
3244

3345
In an existing Codex thread, send `/feedback` or `/feedback` followed by a description of the

0 commit comments

Comments
 (0)