agl 41.0.1 → 41.2.0

package/ts/classes.controllermanagement.ts

@@ -1,6 +1,8 @@
 import * as plugins from './plugins.js';
 import { parseUpgradeBlockers } from './classes.upgradecoordinator.js';
 import {
+  controllerManagementResponseMaximumBytes,
+  controllerManagementTypedRequestPath,
   controllerPackageName,
   controllerProtocolVersion,
   controllerServiceUnitName,
@@ -9,6 +11,7 @@ import {
   type IReq_ControllerUpgradeLaunch,
   type IReq_ControllerUpgradePrepareBegin,
   type IReq_ControllerUpgradeFinalize,
+  type TControllerManagementTypedRequest,
   type TControllerSessionHarnessId,
 } from '../ts_interfaces/index.js';
 import {
@@ -27,6 +30,33 @@ export interface IControllerStatusExpectation {
   upgradeManagementVersion: number;
 }
 
+/**
+ * A declared management protocol (`controllerManagementProtocolVersion` in a package, `managementProtocolVersion`
+ * in a status): a safe integer of 1 or more.
+ */
+export const isControllerManagementProtocolVersion = (valueArg: unknown): valueArg is number => (
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 1
+);
+
+/** A controller a management call is addressed to, by what it declares about its management endpoint. */
+export interface IControllerManagementTarget {
+  /**
+   * The management protocol the controller declares (`controllerManagementProtocolVersion`): the status's own
+   * `managementProtocolVersion` once the controller runs, or what the installed package that runs it declares in
+   * its `package.json`. Absent when it declares none, as every release older than the endpoint.
+   */
+  managementProtocolVersion?: number;
+}
+
+/**
+ * A status read: the identity the status must report, and the declaration that decides how it is read, which comes
+ * from the package expected to run the controller, since there is no status yet. Every caller states it, absent
+ * included.
+ */
+export interface IControllerStatusQuery extends IControllerStatusExpectation {
+  managementProtocolVersion: number | undefined;
+}
+
 const harnessStates = ['starting', 'ready', 'stopping', 'stopped', 'failed'] as const;
 /** The controller protocol version that added each harness to the status document. */
 const controllerHarnessIntroductions: Record<TControllerSessionHarnessId, number> = {
@@ -165,6 +195,8 @@ export const assertControllerStatus = (
     || (expectationArg.protocolVersion !== undefined
       && status.protocolVersion !== expectationArg.protocolVersion)
     || status.upgradeManagementVersion !== expectationArg.upgradeManagementVersion
+    || (status.managementProtocolVersion !== undefined
+      && !isControllerManagementProtocolVersion(status.managementProtocolVersion))
     || !Number.isSafeInteger(status.controllerPid)
     || !Number.isSafeInteger(status.processGroupId)
     || typeof status.processFingerprint !== 'string'
@@ -192,109 +224,273 @@ export const assertControllerStatus = (
   return readableStatus as IControllerStatus;
 };
 
-export const requestControllerUpgradePrepareBegin = async (
+/**
+ * How this build reaches a controller's management methods, decided by the controller's declaration alone: over its
+ * loopback management endpoint when it declares a management protocol, which every later release keeps whatever
+ * transport its browser speaks, and over its controller socket when it declares none (a release older than the
+ * endpoint, such as a source an upgrade recovery restores), which serves them in every release up to this one.
+ * There is no second attempt over the other transport.
+ */
+export const controllerManagementTransport = (
+  targetArg: IControllerManagementTarget,
+): 'http' | 'socket' => (
+  isControllerManagementProtocolVersion(targetArg.managementProtocolVersion) ? 'http' : 'socket'
+);
+
+/** A management request the controller answered with an error, or whose answer this build cannot read. */
+export class ControllerManagementError extends Error {
+  constructor(messageArg: string, public readonly code?: string) {
+    super(messageArg);
+    this.name = 'ControllerManagementError';
+  }
+}
+
+const maximumManagementErrorTextBytes = 4_096;
+
+const isPlainRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg)
+);
+
+/**
+ * Reads one answer of the management endpoint: the envelope must answer this very request (method, request
+ * instance and correlation) and carry `response`; an `error` is the controller's refusal. Keys this build does not
+ * read are left alone, so a later release may add some.
+ */
+const readControllerManagementAnswer = (
+  answerArg: unknown,
+  requestArg: { method: string; requestInstanceId: string; correlationId: string },
+): unknown => {
+  if (
+    !isPlainRecord(answerArg)
+    || answerArg.method !== requestArg.method
+    || answerArg.requestInstanceId !== requestArg.requestInstanceId
+    || !isPlainRecord(answerArg.correlation)
+    || answerArg.correlation.id !== requestArg.correlationId
+    || answerArg.correlation.phase !== 'response'
+    || !Object.hasOwn(answerArg, 'response')
+  ) throw new ControllerManagementError('The controller returned an invalid management answer.', 'protocol_mismatch');
+  if (answerArg.error === undefined) return answerArg.response;
+  if (!isPlainRecord(answerArg.error) || typeof answerArg.error.text !== 'string') {
+    throw new ControllerManagementError('The controller returned an invalid management answer.', 'protocol_mismatch');
+  }
+  const data = answerArg.error.data;
+  const code = isPlainRecord(data) && typeof data.code === 'string' && data.code.length <= 128 ? data.code : undefined;
+  const text = Buffer.byteLength(answerArg.error.text, 'utf8') <= maximumManagementErrorTextBytes
+    ? answerArg.error.text
+    : 'The controller refused the management request.';
+  throw new ControllerManagementError(text, code);
+};
+
+/** Sends one envelope to the management endpoint on 127.0.0.1 and returns the answer's bytes. */
+const postControllerManagementEnvelope = (
   portArg: number,
-  tokenArg: string,
-  targetVersionArg: string,
-  gracePeriodMsArg: number,
-): Promise<IReq_ControllerUpgradePrepareBegin['response']> => {
-  const abortController = new AbortController();
-  const timeout = setTimeout(
-    () => abortController.abort(),
-    controllerUpgradePrepareBeginRequestTimeoutMs,
-  );
+  bodyArg: Buffer,
+  signalArg: AbortSignal,
+): Promise<Buffer> => new Promise<Buffer>((resolve, reject) => {
+  const request = plugins.http.request({
+    protocol: 'http:',
+    hostname: '127.0.0.1',
+    port: portArg,
+    path: controllerManagementTypedRequestPath,
+    method: 'POST',
+    agent: false,
+    signal: signalArg,
+    headers: {
+      Host: `127.0.0.1:${portArg}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'Content-Length': String(bodyArg.byteLength),
+      Connection: 'close',
+    },
+  }, (responseArg) => {
+    const statusCode = responseArg.statusCode ?? 0;
+    const contentType = responseArg.headers['content-type'];
+    if (statusCode !== 200) {
+      responseArg.resume();
+      reject(new ControllerManagementError(
+        `The controller refused the management request with HTTP ${statusCode}.`,
+        'http_refused',
+      ));
+      return;
+    }
+    if (typeof contentType !== 'string' || !/^application\/json(?:;|$)/iu.test(contentType)) {
+      responseArg.resume();
+      reject(new ControllerManagementError('The controller returned an invalid management answer.', 'protocol_mismatch'));
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let byteLength = 0;
+    responseArg.on('data', (chunkArg: Buffer | string) => {
+      const chunk = Buffer.isBuffer(chunkArg) ? chunkArg : Buffer.from(chunkArg);
+      byteLength += chunk.byteLength;
+      if (byteLength > controllerManagementResponseMaximumBytes) {
+        responseArg.destroy();
+        reject(new ControllerManagementError('The controller management answer exceeded its size limit.', 'response_limit'));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    responseArg.once('end', () => resolve(Buffer.concat(chunks, byteLength)));
+    responseArg.once('error', reject);
+  });
+  request.once('error', reject);
+  request.end(bodyArg);
+});
+
+/**
+ * Sends one management request over loopback HTTP: a TypedRequest envelope of exactly `method`, `request`,
+ * `response: null`, `correlation` and `requestInstanceId`, as a TypedRequest client sends it, with no credential
+ * beside what the request itself carries.
+ */
+export const requestControllerManagement = async <T extends TControllerManagementTypedRequest>(
+  portArg: number,
+  methodArg: T['method'],
+  requestArg: T['request'],
+  optionsArg: { timeoutMs: number },
+): Promise<unknown> => {
+  const identity = {
+    method: methodArg,
+    requestInstanceId: plugins.crypto.randomUUID(),
+    correlationId: plugins.crypto.randomUUID(),
+  };
+  const body = Buffer.from(JSON.stringify({
+    method: methodArg,
+    request: requestArg,
+    response: null,
+    correlation: { id: identity.correlationId, phase: 'request' },
+    requestInstanceId: identity.requestInstanceId,
+  }), 'utf8');
+  const timeoutSignal = AbortSignal.timeout(optionsArg.timeoutMs);
+  let answerBytes: Buffer;
+  try {
+    answerBytes = await postControllerManagementEnvelope(portArg, body, timeoutSignal);
+  } catch (errorArg) {
+    if (timeoutSignal.aborted && !(errorArg instanceof ControllerManagementError)) {
+      throw new ControllerManagementError(
+        `The controller did not answer ${methodArg} within ${optionsArg.timeoutMs} ms.`,
+        'timeout',
+      );
+    }
+    throw errorArg;
+  }
+  let answer: unknown;
+  try {
+    const text = answerBytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(answerBytes)) throw new Error('invalid UTF-8');
+    answer = JSON.parse(text);
+  } catch {
+    throw new ControllerManagementError('The controller returned an invalid management answer.', 'protocol_mismatch');
+  }
+  return readControllerManagementAnswer(answer, identity);
+};
+
+/** Fires one management request over the controller socket, for a controller that declares no management protocol. */
+const requestControllerManagementOverSocket = async <T extends TControllerManagementTypedRequest>(
+  portArg: number,
+  methodArg: T['method'],
+  requestArg: T['request'],
+  optionsArg: { timeoutMs: number },
+): Promise<unknown> => {
+  const signal = AbortSignal.timeout(optionsArg.timeoutMs);
   let socket: plugins.typedsocket.TypedSocket | undefined;
   try {
     socket = await plugins.typedsocket.TypedSocket.createClient(
       new plugins.typedrequest.TypedRouter(),
       `http://127.0.0.1:${portArg}`,
-      {
-        autoReconnect: false,
-        maxRetries: 0,
-        abortSignal: abortController.signal,
-      },
+      { autoReconnect: false, maxRetries: 0, abortSignal: signal },
     );
-    const response = await socket.createTypedRequest<IReq_ControllerUpgradePrepareBegin>(
-      'controller.upgrade.prepare.begin',
+    return await socket.createTypedRequest<T>(
+      methodArg,
       undefined,
-      {
-        timeoutMs: controllerUpgradePrepareBeginRequestTimeoutMs,
-        abortSignal: abortController.signal,
-      },
-    ).fire({ token: tokenArg, targetVersion: targetVersionArg, gracePeriodMs: gracePeriodMsArg });
-    if (
-      !response
-      || typeof response !== 'object'
-      || Array.isArray(response)
-      || Object.keys(response).length !== 1
-      || response.accepted !== true
-    ) throw new Error('The controller returned an invalid upgrade preparation response.');
-    return response;
+      { timeoutMs: optionsArg.timeoutMs, abortSignal: signal },
+    ).fire(requestArg);
   } finally {
-    clearTimeout(timeout);
     await socket?.stop();
   }
 };
 
+const requestManagedController = <T extends TControllerManagementTypedRequest>(
+  portArg: number,
+  controllerArg: IControllerManagementTarget,
+  methodArg: T['method'],
+  requestArg: T['request'],
+  optionsArg: { timeoutMs: number },
+): Promise<unknown> => controllerManagementTransport(controllerArg) === 'http'
+  ? requestControllerManagement<T>(portArg, methodArg, requestArg, optionsArg)
+  : requestControllerManagementOverSocket<T>(portArg, methodArg, requestArg, optionsArg);
+
+export const requestControllerUpgradePrepareBegin = async (
+  portArg: number,
+  controllerArg: IControllerManagementTarget,
+  tokenArg: string,
+  targetVersionArg: string,
+  gracePeriodMsArg: number,
+): Promise<IReq_ControllerUpgradePrepareBegin['response']> => {
+  const response = await requestManagedController<IReq_ControllerUpgradePrepareBegin>(
+    portArg,
+    controllerArg,
+    'controller.upgrade.prepare.begin',
+    { token: tokenArg, targetVersion: targetVersionArg, gracePeriodMs: gracePeriodMsArg },
+    { timeoutMs: controllerUpgradePrepareBeginRequestTimeoutMs },
+  );
+  if (
+    !isPlainRecord(response)
+    || Object.keys(response).length !== 1
+    || response.accepted !== true
+  ) throw new Error('The controller returned an invalid upgrade preparation response.');
+  return { accepted: true };
+};
+
 export const requestControllerUpgradeFinalize = async (
   portArg: number,
+  controllerArg: IControllerManagementTarget,
   tokenArg: string,
   modeArg: IReq_ControllerUpgradeFinalize['request']['mode'],
   timeoutMsArg = 60_000,
 ): Promise<IReq_ControllerUpgradeFinalize['response']> => {
-  const socket = await plugins.typedsocket.TypedSocket.createClient(
-    new plugins.typedrequest.TypedRouter(),
-    `http://127.0.0.1:${portArg}`,
-    { autoReconnect: false, maxRetries: 0 },
+  const response = await requestManagedController<IReq_ControllerUpgradeFinalize>(
+    portArg,
+    controllerArg,
+    'controller.upgrade.finalize',
+    { token: tokenArg, mode: modeArg },
+    { timeoutMs: timeoutMsArg },
   );
-  try {
-    return await socket.createTypedRequest<IReq_ControllerUpgradeFinalize>(
-      'controller.upgrade.finalize',
-      undefined,
-      { timeoutMs: timeoutMsArg },
-    ).fire({ token: tokenArg, mode: modeArg });
-  } finally {
-    await socket.stop();
+  if (!isPlainRecord(response) || response.finalized !== true) {
+    throw new Error('The controller returned an invalid upgrade finalization response.');
   }
+  const { continued, failed } = response;
+  if (
+    typeof continued !== 'number' || !Number.isSafeInteger(continued) || continued < 0
+    || typeof failed !== 'number' || !Number.isSafeInteger(failed) || failed < 0
+  ) throw new Error('The controller returned an invalid upgrade finalization response.');
+  return { finalized: true, continued, failed };
 };
 
+/**
+ * Reads a controller's status over the transport the query's declaration picks. The upgrade calls that follow take
+ * the status itself as their target, so from then on the controller's own declaration decides.
+ */
 export const queryControllerStatus = async (
   portArg: number,
-  expectationArg: IControllerStatusExpectation,
+  queryArg: IControllerStatusQuery,
   timeoutMsArg = 2_500,
-): Promise<IControllerStatus> => {
-  const abortController = new AbortController();
-  const timeout = setTimeout(() => abortController.abort(), timeoutMsArg);
-  let socket: plugins.typedsocket.TypedSocket | undefined;
-  try {
-    const router = new plugins.typedrequest.TypedRouter();
-    socket = await plugins.typedsocket.TypedSocket.createClient(
-      router,
-      `http://127.0.0.1:${portArg}`,
-      {
-        autoReconnect: false,
-        maxRetries: 0,
-        abortSignal: abortController.signal,
-      },
-    );
-    const request = socket.createTypedRequest<IReq_ControllerStatus>(
-      'controller.status',
-      undefined,
-      { timeoutMs: timeoutMsArg, abortSignal: abortController.signal },
-    );
-    return assertControllerStatus(await request.fire({}), expectationArg);
-  } finally {
-    clearTimeout(timeout);
-    await socket?.stop();
-  }
-};
+): Promise<IControllerStatus> => assertControllerStatus(
+  await requestManagedController<IReq_ControllerStatus>(
+    portArg,
+    queryArg,
+    'controller.status',
+    {},
+    { timeoutMs: timeoutMsArg },
+  ),
+  queryArg,
+);
 
 export const tryQueryControllerStatus = async (
   portArg: number,
-  expectationArg: IControllerStatusExpectation,
+  queryArg: IControllerStatusQuery,
 ): Promise<IControllerStatus | undefined> => {
   try {
-    return await queryControllerStatus(portArg, expectationArg);
+    return await queryControllerStatus(portArg, queryArg);
   } catch {
     return undefined;
   }
@@ -322,44 +518,25 @@ export const isLoopbackPortListening = async (
 
 export const requestControllerUpgradeLaunch = async (
   portArg: number,
+  controllerArg: IControllerManagementTarget,
   tokenArg: string,
   timeoutMsArg = 15_000,
 ): Promise<IReq_ControllerUpgradeLaunch['response']> => {
-  const abortController = new AbortController();
-  const timeout = setTimeout(() => abortController.abort(), timeoutMsArg);
-  let socket: plugins.typedsocket.TypedSocket | undefined;
-  try {
-    const router = new plugins.typedrequest.TypedRouter();
-    socket = await plugins.typedsocket.TypedSocket.createClient(
-      router,
-      `http://127.0.0.1:${portArg}`,
-      {
-        autoReconnect: false,
-        maxRetries: 0,
-        abortSignal: abortController.signal,
-      },
-    );
-    const response = await socket.createTypedRequest<IReq_ControllerUpgradeLaunch>(
-      'controller.upgrade.launch',
-      undefined,
-      { timeoutMs: timeoutMsArg, abortSignal: abortController.signal },
-    ).fire({ token: tokenArg });
-    if (
-      !response
-      || typeof response !== 'object'
-      || response.accepted !== true
-      || !Number.isSafeInteger(response.workerPid)
-      || response.workerPid < 2
-      || typeof response.logFilePath !== 'string'
-      || !plugins.path.isAbsolute(response.logFilePath)
-    ) {
-      throw new Error(`The controller returned an invalid ${currentCliName} upgrade launch response.`);
-    }
-    return response;
-  } finally {
-    clearTimeout(timeout);
-    await socket?.stop();
-  }
+  const response = await requestManagedController<IReq_ControllerUpgradeLaunch>(
+    portArg,
+    controllerArg,
+    'controller.upgrade.launch',
+    { token: tokenArg },
+    { timeoutMs: timeoutMsArg },
+  );
+  const invalid = new Error(`The controller returned an invalid ${currentCliName} upgrade launch response.`);
+  if (!isPlainRecord(response) || response.accepted !== true) throw invalid;
+  const { workerPid, logFilePath } = response;
+  if (
+    typeof workerPid !== 'number' || !Number.isSafeInteger(workerPid) || workerPid < 2
+    || typeof logFilePath !== 'string' || !plugins.path.isAbsolute(logFilePath)
+  ) throw invalid;
+  return { accepted: true, workerPid, logFilePath };
 };
 
 export const waitUntilControllerExited = async (

package/ts/classes.inferencegateway.ts

@@ -66,9 +66,9 @@ export interface IInferenceGatewayOptions {
   usageLedger: IInferenceUsageLedger;
   /**
    * The confined listener's Unix socket, bound beside the loopback port and made this user's alone (0600, in a private
-   * directory that holds nothing else). It accepts confined credentials alone and serves them the Claude pool's three
-   * endpoints Claude Code uses (`confinedEndpoints`), exactly as the loopback listener serves them; unset, the gateway has
-   * no confined listener and admits no confined credential.
+   * directory that holds nothing else). It accepts confined credentials alone and serves them the three endpoints Claude
+   * Code uses (`confinedEndpoints`) of their pool, the Claude or the ChatGPT pool, exactly as the loopback listener serves
+   * Claude Code on that pool; unset, the gateway has no confined listener and admits no confined credential.
    */
   confinedSocketPath?: string;
 }
@@ -159,8 +159,8 @@ export interface IInferenceGatewayClientOptions {
    */
   sessionScope?: string;
   /**
-   * Where the credential is accepted; `loopback` when unset. A confined credential is a lease of the Claude pool, accepted
-   * on the confined listener alone.
+   * Where the credential is accepted; `loopback` when unset. A confined credential is a lease of the Claude or the ChatGPT
+   * pool, accepted on the confined listener alone, and stays on the pool it was issued for.
    */
   route?: TInferenceGatewayRoute;
 }
@@ -233,8 +233,9 @@ const maximumErrorBodyBytes = 64 * 1024;
 const catalogTag = (modelsArg: unknown): string =>
   `"${plugins.crypto.createHash('sha256').update(JSON.stringify(modelsArg)).digest('base64url')}"`;
 /**
- * What the confined listener serves, by method and path: the Claude pool's endpoints Claude Code uses. Every other
- * method, path and pool is refused there before anything is read or routed.
+ * What the confined listener serves, by method and path: the endpoints Claude Code uses, of the Claude pool or, translated,
+ * of the ChatGPT pool. Every other method and path, every `/openai/` path among them, is refused there before anything is
+ * read or routed.
  */
 const confinedEndpoints: ReadonlySet<string> = new Set(['GET /anthropic/v1/models', 'POST /anthropic/v1/messages',
   'POST /anthropic/v1/messages/count_tokens']);
@@ -476,18 +477,24 @@ export const assertInferenceRoutingPolicy = (policyArg: IInferenceRoutingPolicy)
   }
 };
 
-/** A confined credential is a lease of the Claude pool, admitted only by a gateway with a confined listener. */
+/**
+ * A confined credential is a lease of the Claude or the ChatGPT pool, admitted only by a gateway with a confined listener;
+ * `issuedArg` is the policy it was issued with, which a new policy may not move to another pool.
+ */
 const assertConfinedClient = (policyArg: IInferenceRoutingPolicy, nameArg: string | undefined,
-  socketPathArg: string | undefined): void => {
+  socketPathArg: string | undefined, issuedArg?: IInferenceRoutingPolicy): void => {
   if (socketPathArg === undefined) throw new Error('The gateway has no confined listener.');
-  if (nameArg !== undefined || policyArg.provider !== 'anthropic') {
-    throw new Error('A confined credential is a lease of the Claude pool.');
+  if (nameArg !== undefined || (policyArg.provider !== 'anthropic' && policyArg.provider !== 'openai')) {
+    throw new Error('A confined credential is a lease of the Claude or the ChatGPT pool.');
+  }
+  if (issuedArg !== undefined && policyArg.provider !== issuedArg.provider) {
+    throw new Error('A confined credential stays on the pool it was issued for.');
   }
 };
 
 /**
  * Authenticated Responses and Messages endpoints with bounded, cancelable streaming, on a loopback listener and, for
- * confined credentials, a Unix socket that serves the Claude pool alone.
+ * confined credentials, a Unix socket that serves Claude Code's endpoints alone.
  */
 export class InferenceGateway {
   private readonly clients = new Set<IClient>();
@@ -583,7 +590,7 @@ export class InferenceGateway {
     this.clients.add(client);
     return { baseUrl: `http://${this.host}`, digest: digestArg.toString('hex'), setPolicy: (nextArg) => {
       assertInferenceRoutingPolicy(nextArg);
-      if (routeArg === 'confined') assertConfinedClient(nextArg, nameArg, this.options.confinedSocketPath);
+      if (routeArg === 'confined') assertConfinedClient(nextArg, nameArg, this.options.confinedSocketPath, client.policy);
       client.policy = structuredClone(nextArg);
     }, close: () => {
       this.clients.delete(client);
@@ -713,11 +720,15 @@ export class InferenceGateway {
     try {
       if (routeArg === 'confined') protocol = 'claude';
       client = this.authenticate(requestArg, routeArg);
-      if (routeArg === 'confined' && (client.policy.provider !== 'anthropic'
-        || !confinedEndpoints.has(`${requestArg.method} ${new URL(requestArg.url).pathname}`))) {
-        throw new InferenceRoutingError(404, 'not_found', 'The confined listener serves the Claude pool\'s '
-          + 'GET /anthropic/v1/models, POST /anthropic/v1/messages and POST /anthropic/v1/messages/count_tokens alone.');
+      // On either pool the confined listener serves Claude Code's three endpoints alone, as the loopback listener serves
+      // Claude Code on that pool; a ChatGPT-pool run never reaches a Responses or OpenAI models endpoint.
+      if (routeArg === 'confined' && !confinedEndpoints.has(`${requestArg.method} ${new URL(requestArg.url).pathname}`)) {
+        throw new InferenceRoutingError(404, 'not_found', 'The confined listener serves GET /anthropic/v1/models, '
+          + 'POST /anthropic/v1/messages and POST /anthropic/v1/messages/count_tokens alone.');
       }
+      // From here on a confined request is answered exactly as the loopback listener answers Claude Code on its pool, its
+      // errors included; only the refusals above are the confined listener's own, in Claude's shape.
+      if (routeArg === 'confined' && client.policy.provider !== 'anthropic') protocol = undefined;
       if (this.inFlight >= this.limits.total) throw new InferenceRoutingError(429, 'concurrency_limit', 'The gateway has too many requests in flight.', 1);
       if (client.pending >= this.limits.perClient) throw new InferenceRoutingError(429, 'concurrency_limit', 'This gateway client has too many requests.', 1);
       client.pending += 1;
@@ -998,10 +1009,11 @@ export class InferenceGateway {
               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) => {
+          : new InferenceClaudeUsageTap(answerFormat, (usageArg, cacheStatedArg) => {
             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 });
+              cacheReadTokens: cacheStatedArg.reads ? usageArg.cacheReadTokens : null,
+              cacheWriteTokens: cacheStatedArg.writes ? usageArg.cacheWrite5mTokens + usageArg.cacheWrite1hTokens : null });
           // 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));