agl 40.4.0 → 40.5.1

package/ts/classes.inferencegateway.ts

@@ -1,12 +1,17 @@
 import * as plugins from './plugins.js';
-import { inferenceCredentials, inferencePlanPattern, inferenceProviders } from './functions.proxycontract.js';
-import { InferenceRouter, InferenceRoutingError, type IInferenceClaudeRoute, type IInferenceRoute,
-  type IInferenceRoutingPolicy } from './classes.inferencerouter.js';
+import { inferenceCredentials, inferencePlanPattern, inferenceProviders, type TInferenceCredential,
+  type TInferenceProvider } from './functions.proxycontract.js';
+import { InferenceRouter, InferenceRoutingError, inferenceSpendLimitText, type IInferenceAccountUnavailable,
+  type IInferenceClaudeRoute, type IInferenceRoute, type IInferenceRoutingPolicy,
+  type TInferencePaymentCause } from './classes.inferencerouter.js';
 import { inferenceInputAffinityKeys, inferenceInputStateKeys, inferenceRequestForAccount, InferenceOutputError,
   inspectInferenceOutput, type IInferenceAffinityStore } from './classes.inferenceaffinity.js';
 import { inferenceSessionId, inferenceSessionKey } from './classes.inferencesession.js';
 import type { IInferencePlacementJournal, IInferencePlacementRecord, TInferencePlacementReason } from './classes.inferenceplacement.js';
 import { InferenceClaudeUsageTap, InferenceResponsesUsageTap, type IInferenceUsageTap } from './classes.inferenceusagetap.js';
+import { inferenceAnthropicCheckedBytes, inferenceAnthropicServerToolTypes, inferenceAnthropicSpend,
+  inferenceAnthropicUnpricedRequest, inferenceOpenAiCheckedBytes, inferenceOpenAiSpend,
+  inferenceOpenAiUnpricedRequest } from './classes.inferencespend.js';
 import { usageSessionPattern, type IInferenceTokenCounts, type IInferenceUsageLedger } from './classes.inferenceusage.js';
 
 /**
@@ -281,9 +286,11 @@ const errorResponse = (errorArg: InferenceRoutingError, protocolArg: TProtocol |
   }
   if (protocolArg === 'responses' && errorArg.code === 'accounts_exhausted') {
     const planType = codexPlanType(errorArg.plans);
+    // The OpenAI API keys held by their spend limit are named, as every refusal names them.
+    const spendLimited = inferenceSpendLimitText(errorArg.spendLimited);
     return Response.json({ error: {
       type: 'usage_limit_reached', code: 'usage_limit_reached',
-      message: 'Every eligible account in the AGL proxy pool has reached its usage limit.',
+      message: `Every eligible account in the AGL proxy pool has reached its usage limit.${spendLimited ? ` ${spendLimited}` : ''}`,
       ...(errorArg.retryAfterSeconds ? { resets_at: Math.ceil(Date.now() / 1000) + errorArg.retryAfterSeconds } : {}),
       ...(planType ? { plan_type: planType } : {}),
     } }, { status: 429, headers: errorHeaders(errorArg) });
@@ -315,14 +322,58 @@ const readErrorBody = async (responseArg: Response): Promise<string | undefined>
   } catch { return undefined; }
 };
 
+/** OpenAI's `error.code` values of a 429 that no retry heals: no prepaid credit left, or a spend or usage limit reached. */
+const openAiQuotaCodes = new Set(['credit_balance_exhausted', 'organization_spend_limit_exceeded',
+  'project_spend_limit_exceeded', 'organization_usage_limit_exceeded']);
+
+/**
+ * The payment problem a provider's refusal states about the account the request went on, from its status and its JSON
+ * body (`TInferencePaymentCause`), or `undefined` for any other answer. As the providers document them (read 2026-10-21):
+ * Anthropic answers a billing problem with HTTP 402 `error.type: billing_error`
+ * (https://platform.claude.com/docs/en/api/errors), and an API key's organization at its usage tier's monthly spend cap
+ * with HTTP 429 `error.type: rate_limit_error` and `error.details.error_code: enforced_spend_limit_reached`, no
+ * `retry-after`, until 00:00 UTC on the first of the next month
+ * (https://platform.claude.com/docs/en/api/rate-limits#reaching-your-spend-cap). OpenAI answers an API key out of quota
+ * with HTTP 429 whose `error.code` names the cause (`credit_balance_exhausted`, `organization_spend_limit_exceeded`,
+ * `project_spend_limit_exceeded`, `organization_usage_limit_exceeded`) and whose `error.type` can be
+ * `insufficient_quota`; retrying does not help (https://developers.openai.com/api/docs/guides/error-codes). A Claude
+ * account's subscription states only the billing error; a spend limit set in the Claude Console (HTTP 400
+ * `invalid_request_error`) is not read as one.
+ */
+export const inferencePaymentCause = (providerArg: TInferenceProvider, credentialArg: TInferenceCredential,
+  statusArg: number, bodyArg: unknown): TInferencePaymentCause | undefined => {
+  const error = record(bodyArg) && record(bodyArg.error) ? bodyArg.error : undefined;
+  if (!error) return undefined;
+  if (providerArg === 'anthropic') {
+    if (statusArg === 402 && error.type === 'billing_error') return 'billing';
+    if (credentialArg === 'api_key' && statusArg === 429 && error.type === 'rate_limit_error' && record(error.details)
+      && error.details.error_code === 'enforced_spend_limit_reached') return 'spend_cap';
+    return undefined;
+  }
+  if (credentialArg === 'api_key' && statusArg === 429
+    && ((typeof error.code === 'string' && openAiQuotaCodes.has(error.code)) || error.type === 'insufficient_quota')) {
+    return 'quota';
+  }
+  return undefined;
+};
+
 /**
- * A Claude account's HTTP 402, read up to `maximumErrorBodyBytes`: `billing` when its body is JSON whose `error.type` is
- * `billing_error`, a payment problem of the account. `body` is what the client gets otherwise, byte for byte: the
- * buffered body, or for one over the bound the bytes read so far followed by the rest of the stream.
+ * Whether a provider answer on the route may state a payment problem of its account (`inferencePaymentCause`), so the
+ * gateway reads its body before a byte reaches the client: a Claude account's 402, an API key's 402 or 429.
  */
-const readPaymentRequired = async (responseArg: Response): Promise<{ billing: boolean; body: BodyInit | null }> => {
+const mayStatePaymentProblem = (routeArg: IInferenceRoute | IInferenceClaudeRoute, statusArg: number): boolean =>
+  routeArg.credential === 'api_key' ? statusArg === 429 || (statusArg === 402 && routeArg.provider === 'anthropic')
+    : statusArg === 402 && routeArg.provider === 'anthropic';
+
+/**
+ * A provider refusal that may state a payment problem of the route's account, read up to `maximumErrorBodyBytes`: its
+ * cause when its JSON body states one (`inferencePaymentCause`). `body` is what the client gets otherwise, byte for byte:
+ * the buffered body, or for one over the bound the bytes read so far followed by the rest of the stream.
+ */
+const readPaymentRefusal = async (responseArg: Response, routeArg: IInferenceRoute | IInferenceClaudeRoute):
+Promise<{ cause: TInferencePaymentCause | undefined; body: BodyInit | null }> => {
   const reader = responseArg.body?.getReader();
-  if (!reader) return { billing: false, body: null };
+  if (!reader) return { cause: undefined, body: null };
   const chunks: Uint8Array[] = [];
   let size = 0;
   try {
@@ -333,7 +384,7 @@ const readPaymentRequired = async (responseArg: Response): Promise<{ billing: bo
       size += value.byteLength;
       if (size > maximumErrorBodyBytes) {
         const read = chunks.splice(0);
-        return { billing: false, body: new ReadableStream<Uint8Array>({
+        return { cause: undefined, body: new ReadableStream<Uint8Array>({
           start: (controllerArg) => { for (const chunk of read) controllerArg.enqueue(chunk); },
           pull: async (controllerArg) => {
             const next = await reader.read();
@@ -348,12 +399,11 @@ const readPaymentRequired = async (responseArg: Response): Promise<{ billing: bo
     throw errorArg;
   }
   const bytes = Buffer.concat(chunks);
-  let billing = false;
+  let cause: TInferencePaymentCause | undefined;
   try {
-    const parsed: unknown = JSON.parse(bytes.toString('utf8'));
-    billing = record(parsed) && record(parsed.error) && parsed.error.type === 'billing_error';
+    cause = inferencePaymentCause(routeArg.provider, routeArg.credential, responseArg.status, JSON.parse(bytes.toString('utf8')));
   } catch { /* Not JSON: passed on as it came. */ }
-  return { billing, body: bytes };
+  return { cause, body: bytes };
 };
 
 const readBody = async (requestArg: Request, maximumArg: number): Promise<{ bytes: Uint8Array<ArrayBuffer>; body: Record<string, unknown> }> => {
@@ -383,13 +433,14 @@ const readBody = async (requestArg: Request, maximumArg: number): Promise<{ byte
 };
 
 /**
- * A routing policy as the gateway admits it: a known provider and credential, an API-key pool's provider Anthropic and
- * no plan restriction on it -- a key has no plan -- and bounded account and plan lists.
+ * A routing policy as the gateway admits it: a known provider and credential, no plan restriction on an API-key pool --
+ * a key has no plan -- and bounded account and plan lists. An API-key pool is either provider's: Anthropic's keys serve
+ * Claude Code and Flex, OpenAI's serve Responses requests.
  */
 export const assertInferenceRoutingPolicy = (policyArg: IInferenceRoutingPolicy): void => {
   if (policyArg.provider !== undefined && !inferenceProviders.includes(policyArg.provider)
     || policyArg.credential !== undefined && !inferenceCredentials.includes(policyArg.credential)
-    || policyArg.credential === 'api_key' && (policyArg.provider !== 'anthropic' || policyArg.plans !== undefined)
+    || policyArg.credential === 'api_key' && policyArg.plans !== undefined
     || policyArg.accountIds && (policyArg.accountIds.length > 64 || policyArg.accountIds.some((id) => !/^[a-f0-9]{64}$/.test(id)))
     || policyArg.plans && (policyArg.plans.length > 32 || policyArg.plans.some((plan) => !inferencePlanPattern.test(plan)))) {
     throw new Error('The inference routing policy is invalid.');
@@ -667,31 +718,47 @@ export class InferenceGateway {
         return await this.claudeCountTokens(admitted, sessionKey, model, bytes, claudeSearch, request.headers, signal,
           (routeArg) => { releaseRoute = routeArg.release; });
       }
+      // What of the request has no price: an API key with a monthly spend limit takes no such request. Only a Responses
+      // request goes to an OpenAI API key.
+      const unpriced = claude ? inferenceAnthropicUnpricedRequest(body)
+        : protocol === 'responses' ? inferenceOpenAiUnpricedRequest(body) : undefined;
       // The catalog tag is read alongside the provider request; the pool's catalogs are cached for a minute.
       const catalogTagTask = protocol === 'responses' ? this.currentCatalogTag(client, signal) : Promise.resolve(undefined);
       catalogTagTask.catch(() => undefined);
       const excluded = new Set<string>();
-      /** The accounts of `excluded` this request left for a payment problem, which never count as at their limit. */
-      const paymentExcluded = new Set<string>();
       /**
-       * The last billing error (HTTP 402) a Claude account answered this request with, its bytes as they came: the answer
-       * when no other account can take the request for a reason other than a limit.
+       * The accounts of `excluded` this request left for a reason of their own -- a payment problem, unreadable usage or
+       * spend, no model list, sign-in or access -- and why; they never count as at their limit.
        */
-      let billingAnswer: (() => Response) | undefined;
+      const excludedBecause = new Map<string, IInferenceAccountUnavailable>();
+      /**
+       * The last payment refusal an account answered this request with -- a billing error (HTTP 402), an API key's spend
+       * cap or quota (HTTP 429) -- its bytes as they came: the answer when no other account can take the request for a
+       * reason other than a limit.
+       */
+      let paymentAnswer: (() => Response) | undefined;
       /** Why each account this request left was left, for the placement journal. */
       const leftBecause = new Map<string, TInferencePlacementReason>();
       const exhaustedPlans = new Set<string>();
       let response: Response;
       let quotaError: InferenceRoutingError | undefined;
       const acquire = (accountIdArg: string | undefined): Promise<IInferenceRoute | IInferenceClaudeRoute> => claude
-        ? this.options.router.acquireClaude(model, admitted.policy, signal, { exclude: excluded, paymentExcluded,
-          ...(accountIdArg === undefined ? {} : { accountId: accountIdArg }) })
+        ? this.options.router.acquireClaude(model, admitted.policy, signal, { exclude: excluded, excludedBecause,
+          ...(unpriced === undefined ? {} : { unpriced }),
+          // A Claude session carries no state bound to its account: one placed on an API key returns to a Claude account
+          // as soon as one can take its request.
+          ...(accountIdArg === undefined ? {} : { accountId: accountIdArg, returnToBetterTier: true }) })
         : this.options.router.acquire(model, admitted.policy, signal, {
-          exclude: excluded,
+          exclude: excluded, excludedBecause,
           ...(record(body.reasoning) && typeof body.reasoning.effort === 'string' ? { reasoningEffort: body.reasoning.effort } : {}),
           ...(typeof body.service_tier === 'string' ? { serviceTier: body.service_tier } : {}),
           ...(admitted.codexClientVersion ? { clientVersion: admitted.codexClientVersion } : {}),
-          ...(accountIdArg === undefined ? {} : { accountId: accountIdArg }),
+          // An OpenAI API key takes Responses requests alone, never a translated Messages request.
+          ...(protocol === 'responses' ? { apiKeys: true } : {}),
+          ...(unpriced === undefined ? {} : { unpriced }),
+          // A Responses session placed on an API key returns to a ChatGPT account when one can take its request, but never
+          // while the request carries state bound to its account.
+          ...(accountIdArg === undefined ? {} : { accountId: accountIdArg, returnToBetterTier: !inferenceRequestHasAccountState(body) }),
         });
       // At most 64 accounts can be tried; bound contention retries separately as well.
       for (let decision = 0; decision < 128; decision++) {
@@ -712,9 +779,10 @@ export class InferenceGateway {
           const exhausted = errorArg instanceof InferenceRoutingError && errorArg.code === 'accounts_exhausted';
           // A session moves when its account is at its limit, no longer in the pool at all, outside the client's
           // account restriction, or lapsed; a Claude session also when its account takes no request for a reason of
-          // its own. ChatGPT conversation state stays with the account that holds it.
-          const left = sessionAccountOutsidePool(errorArg)
-            || (claude && preferred !== undefined && sessionAccountUnavailable(errorArg, preferred));
+          // its own, and a Responses session when its account -- an OpenAI API key -- is held with a payment problem.
+          // Any other refusal of its own keeps Responses conversation state with the account that holds it.
+          const left = sessionAccountOutsidePool(errorArg) || (preferred !== undefined && sessionAccountUnavailable(errorArg, preferred)
+            && (claude || (errorArg as InferenceRoutingError).reason === 'payment_problem'));
           if (!preferred || !(errorArg instanceof InferenceRoutingError) || (!exhausted && !left && required)) throw errorArg;
           if (exhausted) {
             quotaError = errorArg;
@@ -723,20 +791,28 @@ export class InferenceGateway {
           if (exhausted || left) {
             excluded.add(preferred);
             if (!leftBecause.has(preferred)) leftBecause.set(preferred, placementReason(errorArg));
-            if (errorArg.reason === 'payment_problem') paymentExcluded.add(preferred);
+            if (errorArg.unavailable) excludedBecause.set(preferred, errorArg.unavailable);
           }
           try {
             route = await acquire(undefined);
           } catch (acquireErrorArg) {
             const limited = acquireErrorArg instanceof InferenceRoutingError && acquireErrorArg.code === 'accounts_exhausted';
             if (limited && quotaError) {
-              throw new InferenceRoutingError(429, 'accounts_exhausted', 'The eligible accounts reached their provider limits.',
-                acquireErrorArg.retryAfterSeconds ?? quotaError.retryAfterSeconds, [...exhaustedPlans, ...acquireErrorArg.plans]);
+              // The API keys either refusal found held by their spend limit are named: the session's own, which the
+              // second judgement left out, among them.
+              const spendLimited = [...quotaError.spendLimited, ...acquireErrorArg.spendLimited];
+              throw new InferenceRoutingError(429, 'accounts_exhausted', spendLimited.length
+                ? `The eligible accounts reached their limits. ${inferenceSpendLimitText(spendLimited)}`
+                : 'The eligible accounts reached their provider limits.',
+              acquireErrorArg.retryAfterSeconds ?? quotaError.retryAfterSeconds, [...exhaustedPlans, ...acquireErrorArg.plans],
+              undefined, undefined, undefined, spendLimited);
             }
-            // No other account takes the request for a reason other than a limit: the client gets Anthropic's own 402.
-            if (!limited && billingAnswer) {
-              this.reportRequestFailure({ status: 402, code: 'provider_error', protocol });
-              return billingAnswer();
+            // No other account takes the request for a reason other than a limit: the client gets the provider's own
+            // payment refusal.
+            if (!limited && paymentAnswer) {
+              const answer = paymentAnswer();
+              this.reportRequestFailure({ status: answer.status, code: 'provider_error', protocol });
+              return answer;
             }
             throw acquireErrorArg;
           }
@@ -752,37 +828,40 @@ export class InferenceGateway {
         if (binding?.accountId !== route.accountId) {
           this.recordPlacement({ sessionKey, provider: route.provider, fromAccountId: binding?.accountId ?? null,
             toAccountId: route.accountId, score: route.score,
-            reason: binding ? leftBecause.get(binding.accountId) ?? 'left_pool' : 'new' });
+            reason: route.returned ? 'returned' : binding ? leftBecause.get(binding.accountId) ?? 'left_pool' : 'new' });
         }
-        // Claude Code's own bytes go to Anthropic unchanged.
+        // Claude Code's own bytes go to Anthropic unchanged, except that an API key with a monthly spend limit gets the body
+        // the price check read, asking for the standard service tier only, the one the price table prices.
         response = route.provider === 'anthropic'
-          ? await this.claudeMessages(route, pathname, claudeSearch, request.headers, bytes, signal)
+          ? await this.claudeMessages(route, pathname, claudeSearch, request.headers,
+            route.spendLimit ? inferenceAnthropicCheckedBytes(body) : bytes, signal)
           : protocol === 'messages'
             ? await this.messages(new Request(new URL(pathname, request.url), { method: 'POST', headers: request.headers, signal }),
               prepared.body ?? body, route)
             : await this.responses(prepared.body ?? body, route, request.headers, signal);
-        if (route.provider === 'anthropic' && route.credential === 'subscription' && response.status === 402) {
-          // A billing error is a payment problem of the account: it leaves rotation, and the request goes to another
-          // account before a byte reaches the client, never to this one again. Any other 402 passes as it came.
-          const paymentRequired = await readPaymentRequired(response);
-          if (paymentRequired.billing) {
-            this.options.router.reportPaymentProblem(route.accountId);
+        if (mayStatePaymentProblem(route, response.status)) {
+          // A payment problem of the account -- a billing error, or an API key's spend cap or quota -- takes it out of
+          // rotation, and the request goes to another account before a byte reaches the client, never to this one
+          // again. Any other answer passes as it came.
+          const refusal = await readPaymentRefusal(response, route);
+          if (refusal.cause) {
+            const unavailable = this.options.router.reportPaymentProblem(route.accountId, refusal.cause);
             const answered = route;
-            const answer = { body: paymentRequired.body, headers: new Headers(response.headers) };
-            billingAnswer = () => {
+            const answer = { status: response.status, body: refusal.body, headers: new Headers(response.headers) };
+            paymentAnswer = () => {
               answer.headers.set('cache-control', 'no-store');
               answer.headers.set('x-agl-account-id', answered.accountId);
               answer.headers.set('x-agl-plan', answered.plan);
-              return new Response(answer.body, { status: 402, headers: answer.headers });
+              return new Response(answer.body, { status: answer.status, headers: answer.headers });
             };
             route.release();
             releaseRoute = undefined;
             excluded.add(route.accountId);
-            paymentExcluded.add(route.accountId);
+            excludedBecause.set(route.accountId, unavailable);
             leftBecause.set(route.accountId, 'unavailable');
             continue;
           }
-          response = new Response(paymentRequired.body, { status: 402, headers: response.headers });
+          response = new Response(refusal.body, { status: response.status, headers: response.headers });
         }
         if (response.status === 429) {
           const seconds = this.options.router.retryAfterSeconds(response.headers);
@@ -830,12 +909,23 @@ export class InferenceGateway {
         const recordUsage = this.usageRecorder(client, route, sessionKey);
         const answerFormat = (response.headers.get('content-type') ?? '').toLowerCase().startsWith('text/event-stream') ? 'sse' : 'json';
         const tap: IInferenceUsageTap | undefined = !response.ok || pathname === '/v1/messages/count_tokens' ? undefined
-          : protocol === 'responses' ? new InferenceResponsesUsageTap(body.stream === true ? 'sse' : 'json', recordUsage)
+          : protocol === 'responses' ? new InferenceResponsesUsageTap(body.stream === true ? 'sse' : 'json', recordUsage,
+            // An OpenAI API key's answer is priced as it ends; one cut before OpenAI stated its usage counts nowhere, and the
+            // journal says so.
+            route.credential === 'api_key' ? (answeredArg) => {
+              const spent = inferenceOpenAiSpend(answeredArg, route.model.modelId, Date.now());
+              if (spent) this.options.router.recordSpend(accountId, route.loginId, spent);
+              else this.options.router.uncountedSpend(accountId, answeredArg.model ?? route.model.modelId);
+            } : undefined)
           : new InferenceClaudeUsageTap(answerFormat, (usageArg) => {
             if (route.provider === 'anthropic') this.options.router.countTokens(accountId, usageArg);
             recordUsage({ inputTokens: usageArg.inputTokens, outputTokens: usageArg.outputTokens,
               cacheReadTokens: usageArg.cacheReadTokens, cacheWriteTokens: usageArg.cacheWrite5mTokens + usageArg.cacheWrite1hTokens });
-          });
+          // An API key's answer is priced as it ends, and its spend counts against the key's limit from then on.
+          }, route.provider === 'anthropic' && route.credential === 'api_key' ? (answeredArg) => {
+            const spent = inferenceAnthropicSpend(answeredArg, route.model.modelId, Date.now(), inferenceAnthropicServerToolTypes(body));
+            if (spent) this.options.router.recordSpend(accountId, route.loginId, spent);
+          } : undefined);
         if (!response.ok) this.reportRequestFailure({ status: response.status, code: 'provider_error', protocol });
         return this.streamResponse(inspected, headers, signal, finish,
           { protocol, accountId, responsesSse: response.ok && protocol === 'responses' && body.stream === true, ...(tap ? { tap } : {}) });
@@ -920,13 +1010,27 @@ export class InferenceGateway {
     this.turnStates.set(id, { accountId: accountIdArg, until: Date.now() + turnStateLifetimeMs });
   }
 
+  /**
+   * Sends a Responses request on the route: to a ChatGPT account through the ChatGPT backend, normalized for it, or to an
+   * OpenAI API key through OpenAI's API (`OPENAI_API_BASE_URL/responses`) on the key's own connection, as Codex sent it,
+   * with only its `model` rewritten -- and for a key with a monthly spend limit, the service tier it was checked for
+   * (`inferenceOpenAiCheckedBytes`). Codex's thread headers travel with it; a turn token only to the account that issued
+   * it. An authorization failure is about the account the gateway chose, never the client's credential: a key OpenAI
+   * rejects (401) is the proxy's to explain, in its own words.
+   */
   private async responses(bodyArg: Record<string, unknown>, routeArg: IInferenceRoute, requestHeadersArg: Headers,
     signalArg: AbortSignal): Promise<Response> {
-    let body: Record<string, unknown>;
-    try {
-      body = plugins.openAiProvider.normalizeOpenAiChatGptResponsesRequest(bodyArg);
-    } catch {
-      throw new InferenceRoutingError(400, 'invalid_request', 'The Responses instruction prefix must contain text only.');
+    const apiKey = routeArg.credential === 'api_key';
+    let body: Uint8Array<ArrayBuffer> | string;
+    if (apiKey) {
+      body = routeArg.spendLimit ? inferenceOpenAiCheckedBytes(bodyArg, routeArg.model.wireModel)
+        : JSON.stringify({ ...bodyArg, model: routeArg.model.wireModel });
+    } else {
+      try {
+        body = JSON.stringify({ ...plugins.openAiProvider.normalizeOpenAiChatGptResponsesRequest(bodyArg), model: routeArg.model.wireModel });
+      } catch {
+        throw new InferenceRoutingError(400, 'invalid_request', 'The Responses instruction prefix must contain text only.');
+      }
     }
     const transport = routeArg.connection.settings.fetch;
     if (!transport) throw new Error('The provider has no inference transport.');
@@ -938,10 +1042,24 @@ export class InferenceGateway {
     const turnState = requestHeadersArg.get(turnStateHeader);
     if (turnState !== null && this.turnStateOwner(turnState) === routeArg.accountId) upstreamHeaders.set(turnStateHeader, turnState);
     // No caller-controlled URL or upstream credential crosses this boundary.
-    const response = await transport(`${plugins.openAiProvider.OPENAI_CHATGPT_CODEX_BASE_URL}/responses`, {
-      method: 'POST', headers: upstreamHeaders,
-      body: JSON.stringify({ ...body, model: routeArg.model.wireModel }), signal: signalArg,
-    });
+    let response: Response;
+    try {
+      response = await transport(`${apiKey ? plugins.openAiProvider.OPENAI_API_BASE_URL
+        : plugins.openAiProvider.OPENAI_CHATGPT_CODEX_BASE_URL}/responses`, {
+        method: 'POST', headers: upstreamHeaders, body, signal: signalArg,
+      });
+    } catch (errorArg) {
+      if (errorArg instanceof plugins.openAiProvider.OpenAiApiKeyAuthError && errorArg.status === 401) {
+        throw new InferenceRoutingError(503, 'account_unauthorized', 'OpenAI rejected the API key serving this session. Add '
+          + 'a valid key in AGL Accounts or with `authswitch account add openai-api-key`, and remove the rejected one.');
+      }
+      if (errorArg instanceof plugins.openAiProvider.OpenAiApiKeyAuthError && errorArg.status === 403) {
+        return Response.json({ error: { code: 'provider_forbidden',
+          message: 'OpenAI refused the API key serving this session: it lacks the permission this request needs.' } },
+        { status: 403, headers: { 'content-type': 'application/json' } });
+      }
+      throw errorArg;
+    }
     const headers = new Headers();
     response.headers.forEach((value, name) => {
       if (forwardedResponseHeaders.has(name) || isCodexResponseHeader(name)) headers.set(name, value);
@@ -1092,11 +1210,13 @@ export class InferenceGateway {
     streamArg: { protocol: TProtocol; accountId: string; responsesSse: boolean; tap?: IInferenceUsageTap }): Promise<Response> {
     const tap = streamArg.tap;
     if (!responseArg.body && !streamArg.responsesSse) {
-      tap?.end(); finishArg(); return new Response(null, { status: responseArg.status, headers: headersArg });
+      tap?.end(true); finishArg(); return new Response(null, { status: responseArg.status, headers: headersArg });
     }
     const reader = (responseArg.body ?? new ReadableStream<Uint8Array>({ start(controllerArg) { controllerArg.close(); } })).getReader();
     let finished = false;
     let cancelled = false;
+    /** The provider's body was read to its end. */
+    let whole = false;
     let relayed = 0;
     const report = this.options.reportStreamCut ?? writeStreamCut;
     const failure = (errorArg: unknown): InferenceRoutingError => {
@@ -1118,7 +1238,7 @@ export class InferenceGateway {
       finished = true;
       signalArg.removeEventListener('abort', abort);
       reader.releaseLock();
-      tap?.end();
+      tap?.end(whole);
       finishArg();
     };
     const abort = () => { void reader.cancel(signalArg.reason).finally(finish).catch(() => undefined); };
@@ -1149,7 +1269,7 @@ export class InferenceGateway {
           // provider's stream. The signal need not say so, as Node's fetch stops a request's signal from following
           // the listener's abort once that request is collected.
           if (cancelled) return;
-          if (result.done) { controllerArg.close(); finish(); }
+          if (result.done) { whole = true; controllerArg.close(); finish(); }
           else { relayed += result.value.byteLength; controllerArg.enqueue(result.value); tap?.chunk(result.value); }
         } catch (errorArg) {
           const error = failure(errorArg);

package/ts/classes.inferenceplacement.ts

@@ -6,14 +6,16 @@ import { inferenceProviders, type TInferenceProvider } from './functions.proxyco
  * the account it had: `exhausted` (a window used up, or the provider refusing until a time it named), `reserved` (its
  * usage threshold reached), `cooling` (resting after a provider 429 another request met), `provider_429` (the provider
  * refused this request with a 429), `left_pool` (removed, signed out, or taken by a native tool), `outside_restriction`
- * (the client's account restriction leaves it out), `lapsed` (its subscription ended) or `unavailable` (a Claude
- * account that takes no request for a reason of its own: no usage reading, no model list, no access, or no such model).
+ * (the client's account restriction leaves it out), `lapsed` (its subscription ended), `unavailable` (an account that
+ * takes no request for a reason of its own: no usage reading, no model list, no access, no such model, or a payment
+ * problem) or `returned` (the session was on an API key, and a subscription of the pool could take its request again).
+ * An AGL older than a reason it reads among the latest placements fails `agl proxy status` until that entry ages out.
  */
 export type TInferencePlacementReason = 'new' | 'exhausted' | 'reserved' | 'cooling' | 'provider_429' | 'left_pool'
-  | 'outside_restriction' | 'lapsed' | 'unavailable';
+  | 'outside_restriction' | 'lapsed' | 'unavailable' | 'returned';
 
 export const inferencePlacementReasons: readonly TInferencePlacementReason[] = Object.freeze(['new', 'exhausted', 'reserved',
-  'cooling', 'provider_429', 'left_pool', 'outside_restriction', 'lapsed', 'unavailable']);
+  'cooling', 'provider_429', 'left_pool', 'outside_restriction', 'lapsed', 'unavailable', 'returned']);
 
 /** A placement as the gateway reports it: the session by its key (`inferenceSessionKey`), never stored as it is. */
 export interface IInferencePlacementRecord {