@yansigit/opencodex 2.31.3 → 2.33.0

package/src/images/loop.ts

@@ -18,7 +18,7 @@ import type { AdapterEvent, OcxMessage, OcxParsedRequest, OcxProviderContinuatio
 import { namespacedToolName, toolChoiceToolPredicate } from "../types";
 import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
 import type { AttemptRecoveryKind } from "../usage/log";
-import { bridgeToResponsesSSE } from "../bridge";
+import { bridgeToResponsesSSE, diagnoseAdapterEvent, type BridgeDiagnosticContext } from "../bridge";
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { fetchWithResetRetry, prepareSameTarget429Wait } from "../lib/upstream-retry";
@@ -35,6 +35,7 @@ import { submitVideoJob } from "./xai-video-client";
 import { downloadVideoToArtifact, createImageBudget, pruneArtifacts } from "./artifacts";
 import { IMAGE_GEN_TOOL_NAME, VIDEO_GEN_TOOL_NAME } from "./synthetic-tool";
 import type { ImageBridgePlan, VideoBridgePlan } from "./types";
+import { OcxRequestValidationError } from "../lib/errors";
 
 const SSE_HEADERS = {
   "Content-Type": "text/event-stream",
@@ -209,8 +210,14 @@ function extractIterationThinking(events: AdapterEvent[]): OcxThinkingContent[]
   return parts;
 }
 
-function jsonError(status: number, message: string): Response {
-  return new Response(JSON.stringify({ error: { message, type: "upstream_error", code: null } }), {
+function jsonError(status: number, message: string, errorType = "upstream_error", code: string | null = null): Response {
+  return new Response(JSON.stringify({
+    error: {
+      message,
+      type: errorType,
+      code,
+    },
+  }), {
     status,
     headers: { "Content-Type": "application/json" },
   });
@@ -219,7 +226,12 @@ function jsonError(status: number, message: string): Response {
 /** Hard provider/parse failure inside an iteration. The eager first iteration converts it to a
  *  non-2xx jsonError; later (already-streaming) iterations surface it as an in-stream error event. */
 class LoopError extends Error {
-  constructor(readonly status: number, message: string) {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly errorType?: string,
+    readonly code?: string,
+  ) {
     super(message);
     this.name = "LoopError";
   }
@@ -245,6 +257,8 @@ export interface ImageBridgeDeps {
   onAttemptSend?: (recovery?: AttemptRecoveryKind) => void;
   /** Called after each upstream request is built (parity with web-search / normal path). */
   onRequestBuilt?: (request: AdapterRequest) => void;
+  /** Validate the final adapter before every cached replay or request build. */
+  validateAdapter?: (parsed: OcxParsedRequest, adapter: ProviderAdapter) => void;
   abortSignal?: AbortSignal;
   onFirstOutput?: () => void;
   /** Max image-generation rounds before forcing a final answer. Defaults to 3; clamped to [0, 10]. */
@@ -270,6 +284,8 @@ export interface ImageBridgeDeps {
   onCompletedResponse?: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => void;
   /** WebSocket Responses path only — leave response id empty for protocol compatibility. */
   forceEmptyResponseId?: boolean;
+  /** Internal, opt-in structural stream diagnostics shared with the final bridge. */
+  diagnostic?: BridgeDiagnosticContext;
 }
 
 /**
@@ -487,6 +503,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
        * header deadline. The caller owns same-target 429 replays and key rotation around it.
        */
       const fetchOnce = async (requestAdapter: ProviderAdapter, recovery?: AttemptRecoveryKind): Promise<IterationResponse> => {
+        deps.validateAdapter?.(iterParsed, requestAdapter);
         let request: AdapterRequest;
         if (cachedRequest !== undefined && cachedAdapter === requestAdapter) {
           request = cachedRequest;
@@ -609,6 +626,9 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       return prepared;
     } catch (error) {
       if (isTranslatorBudgetExceededError(error)) throw error;
+      if (error instanceof OcxRequestValidationError) {
+        throw new LoopError(error.status, error.message, "invalid_request_error", "invalid_request_error");
+      }
       if (headerDeadline.didExpire()) {
         throw new LoopError(504, `Provider response-header timeout after ${connectTimeoutMs}ms during image-bridge`);
       }
@@ -638,6 +658,10 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         inactivityTimeoutMs: stallTimeoutMs,
         translatorBudget,
       })) {
+        if (deps.diagnostic) {
+          deps.diagnostic.adapterName = prepared.responseAdapter.name;
+          diagnoseAdapterEvent(deps.diagnostic, event);
+        }
         if (event.type === "heartbeat") yield event;
         else events.push(event);
       }
@@ -674,7 +698,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       firstPrepared = await prepareIterationDrained(maxRounds <= 0);
     } catch (e) {
       if (abortSignal) abortSignal.removeEventListener("abort", linkAbort);
-      if (e instanceof LoopError) return jsonError(e.status, e.message);
+      if (e instanceof LoopError) return jsonError(e.status, e.message, e.errorType, e.code ?? null);
       throw e;
     }
   }
@@ -920,7 +944,13 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
             yield {
               type: "error",
               message: e instanceof LoopError ? e.message : (e instanceof Error ? e.message : String(e)),
-              ...(e instanceof LoopError ? { status: e.status } : {}),
+              ...(e instanceof LoopError ? {
+                status: e.status,
+                ...(e.errorType !== undefined || e.status === 400
+                  ? { errorType: e.errorType ?? "upstream_error" }
+                  : {}),
+                ...(e.code !== undefined ? { code: e.code } : {}),
+              } : {}),
               ...(hiddenUsage ? { usage: hiddenUsage } : {}),
             };
           }
@@ -949,6 +979,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         onUsage: (usage: OcxUsage | undefined) => deps.onUsage?.(usage),
       } : {}),
       ...(deps.onCompletedResponse ? { onCompletedResponse: deps.onCompletedResponse } : {}),
+      ...(deps.diagnostic ? { diagnostic: deps.diagnostic } : {}),
     },
   );
   return new Response(sse, { headers: SSE_HEADERS });

package/src/images/plan.ts

@@ -48,11 +48,12 @@ export async function planImageBridge(
   if (config.images?.bridgeEnabled !== true) return undefined;
   if (!parsed._imageGeneration) return undefined;
   const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice);
-  const toolNames = new Set(
-    [...parsed._imageGeneration.toolNames, IMAGE_GEN_TOOL_NAME]
-      .filter(name => toolAllowed({ name })),
-  );
+  const toolNames = new Set([...parsed._imageGeneration.toolNames].filter(name => toolAllowed({ name })));
+  if (toolAllowed({ name: IMAGE_GEN_TOOL_NAME })) toolNames.add(IMAGE_GEN_TOOL_NAME);
   if (toolNames.size === 0) return undefined;
+  // Responses advertises and rewrites authorized aliases to this synthetic name, so the loop
+  // must always intercept it once any image-generation name has armed the bridge.
+  toolNames.add(IMAGE_GEN_TOOL_NAME);
   // Don't intercept for OpenAI native passthrough
   const host = (() => { try { return new URL(routedProvider.baseUrl).hostname; } catch { return ""; } })();
   if (host === "api.openai.com") return undefined;

package/src/integrations/ownership-policy.ts

@@ -0,0 +1,141 @@
+/**
+ * Client-scoped exceptions to strict managed-fragment ownership.
+ *
+ * Most clients must preserve every byte represented by their managed
+ * contribution. A client that persists runtime-derived fields back into an
+ * OpenCodex-owned fragment needs a narrower contract: name the exact paths it
+ * may rewrite, then fingerprint everything else. Keeping that policy here
+ * prevents a client quirk from weakening the shared classifier.
+ */
+import {
+  OPENCODE_PROVIDER_ID,
+  type ManagedContribution,
+  type ManagedFragment,
+} from "../clients/config-export";
+import { canonicalContribution, fingerprint } from "./ownership";
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pathStartsWith(path: readonly string[], prefix: readonly string[]): boolean {
+  return prefix.length <= path.length && prefix.every((part, index) => path[index] === part);
+}
+
+/** Delete one nested object member and prune only the empty ancestors created by that deletion. */
+function deletePath(root: unknown, path: readonly string[]): void {
+  if (!isObject(root) || path.length === 0) return;
+  const parents: Array<{ parent: JsonObject; key: string }> = [];
+  let cursor: JsonObject = root;
+  for (let index = 0; index < path.length - 1; index += 1) {
+    const key = path[index]!;
+    const next = cursor[key];
+    if (!isObject(next)) return;
+    parents.push({ parent: cursor, key });
+    cursor = next;
+  }
+  delete cursor[path[path.length - 1]!];
+  for (let index = parents.length - 1; index >= 0; index -= 1) {
+    if (Object.keys(cursor).length > 0) break;
+    const { parent, key } = parents[index]!;
+    delete parent[key];
+    cursor = parent;
+  }
+}
+
+function cloneFragment(fragment: ManagedFragment): ManagedFragment {
+  return {
+    path: [...fragment.path],
+    value: structuredClone(fragment.value),
+  };
+}
+
+/**
+ * Paths a client is documented to derive after OpenCodex writes its block.
+ *
+ * ZCode 3.8.1 persists reasoning and output defaults for every generated
+ * model. It may also fill a context default when OpenCodex intentionally
+ * omitted one; an authoritative context emitted by OpenCodex remains
+ * protected and is never listed here.
+ */
+export function refreshablePathsOf(
+  contribution: ManagedContribution,
+): readonly (readonly string[])[] {
+  if (contribution.clientId !== "zcode") return [];
+  const fragment = contribution.fragments.find(candidate => (
+    candidate.path.length === 2
+    && candidate.path[0] === "provider"
+    && candidate.path[1] === OPENCODE_PROVIDER_ID
+  ));
+  if (!fragment || !isObject(fragment.value) || !isObject(fragment.value.models)) return [];
+
+  const paths: string[][] = [];
+  for (const modelId of Object.keys(fragment.value.models).sort()) {
+    const entry = fragment.value.models[modelId];
+    if (!isObject(entry)) continue;
+    const base = [...fragment.path, "models", modelId];
+    paths.push([...base, "reasoning"]);
+    paths.push([...base, "limit", "output"]);
+    const limit = entry.limit;
+    if (!isObject(limit) || typeof limit.context !== "number") {
+      paths.push([...base, "limit", "context"]);
+    }
+  }
+  return paths;
+}
+
+export function validRefreshablePaths(
+  contribution: ManagedContribution,
+  value: unknown,
+): value is readonly (readonly string[])[] {
+  if (contribution.clientId !== "zcode" || !Array.isArray(value) || value.length === 0) {
+    return false;
+  }
+  const fragment = contribution.fragments.find(candidate => (
+    candidate.path.length === 2
+    && candidate.path[0] === "provider"
+    && candidate.path[1] === OPENCODE_PROVIDER_ID
+  ));
+  if (!fragment || !isObject(fragment.value) || !isObject(fragment.value.models)) return false;
+
+  const modelIds = new Set(Object.keys(fragment.value.models));
+  const seen = new Set<string>();
+  return value.every(path => {
+    if (!Array.isArray(path) || !path.every(part => typeof part === "string")) return false;
+    const modelId = path[3];
+    const isReasoning = path.length === 5 && path[4] === "reasoning";
+    const isLimitDefault = path.length === 6
+      && path[4] === "limit"
+      && (path[5] === "output" || path[5] === "context");
+    const key = path.join("\u0000");
+    if (
+      path[0] !== "provider"
+      || path[1] !== OPENCODE_PROVIDER_ID
+      || path[2] !== "models"
+      || typeof modelId !== "string"
+      || !modelIds.has(modelId)
+      || (!isReasoning && !isLimitDefault)
+      || seen.has(key)
+    ) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Fingerprint a contribution after removing only its explicitly refreshable paths. */
+export function protectedContributionFingerprint(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): string {
+  const fragments = contribution.fragments.map(cloneFragment);
+  for (const refreshablePath of refreshablePaths) {
+    for (const fragment of fragments) {
+      if (!pathStartsWith(refreshablePath, fragment.path)) continue;
+      deletePath(fragment.value, refreshablePath.slice(fragment.path.length));
+      break;
+    }
+  }
+  return fingerprint(canonicalContribution({ ...contribution, fragments }));
+}

package/src/integrations/ownership.ts

@@ -41,6 +41,16 @@ export interface OwnershipRecord {
   fileFingerprint: string;
   /** Hash of our contribution — detects catalog/port drift. */
   blockFingerprint: string;
+  /**
+   * Hash of the fields the client must not rewrite. Present only when a
+   * client has explicitly declared runtime-derived paths below.
+   */
+  protectedBlockFingerprint?: string;
+  /**
+   * Exact document paths a client may derive after apply. These are recorded
+   * per operation so later catalog changes cannot widen an older grant.
+   */
+  refreshablePaths?: readonly (readonly string[])[];
   /** The exact paths we own. Removal touches these and nothing else. */
   fragmentPaths: readonly (readonly string[])[];
   /**

package/src/integrations/state.ts

@@ -13,6 +13,11 @@ import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { SNAPSHOT_RETENTION } from "./journal";
 import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
+import {
+  protectedContributionFingerprint,
+  refreshablePathsOf,
+  validRefreshablePaths,
+} from "./ownership-policy";
 import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
@@ -106,10 +111,10 @@ export function blockedContainerPath(
  * values lets another integration or a user add a sibling without blocking a
  * later refresh, while a change inside our block still fails closed.
  */
-function recordedFragmentFingerprint(
+function recordedContribution(
   doc: unknown,
   record: OwnershipRecord,
-): string | null {
+): ManagedContribution | null {
   if (
     !Array.isArray(record.fragmentPaths)
     || record.fragmentPaths.length === 0
@@ -125,10 +130,44 @@ function recordedFragmentFingerprint(
     if (value === undefined) return null;
     fragments.push({ path, value });
   }
-  return fingerprint(canonicalContribution({
+  return {
     clientId: record.clientId,
     fragments,
-  }));
+  };
+}
+
+/**
+ * Prove that every protected field still matches what OpenCodex wrote.
+ *
+ * New records carry an operation-scoped protected fingerprint and the exact
+ * paths excluded from it. Legacy records can recover only when the desired
+ * contribution has not moved since apply; otherwise catalog drift and a
+ * foreign edit are indistinguishable, so the classifier keeps failing closed.
+ */
+function recordedBlockIsOwned(
+  doc: unknown,
+  record: OwnershipRecord,
+  desired: ManagedContribution,
+): boolean {
+  const observed = recordedContribution(doc, record);
+  if (!observed) return false;
+  if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
+
+  if (
+    typeof record.protectedBlockFingerprint === "string"
+    && validRefreshablePaths(observed, record.refreshablePaths)
+    && record.refreshablePaths.length > 0
+  ) {
+    return protectedContributionFingerprint(observed, record.refreshablePaths)
+      === record.protectedBlockFingerprint;
+  }
+
+  const desiredFingerprint = fingerprint(canonicalContribution(desired));
+  if (desiredFingerprint !== record.blockFingerprint) return false;
+  const legacyPaths = refreshablePathsOf(desired);
+  return legacyPaths.length > 0
+    && protectedContributionFingerprint(observed, legacyPaths)
+      === protectedContributionFingerprint(desired, legacyPaths);
 }
 
 /**
@@ -191,7 +230,7 @@ export function classifyIntegration(input: {
    * conflict no matter what the rest of the file looks like, so the sibling-
    * edit exemption below can never mask it.
    */
-  if (recordedFragmentFingerprint(input.parsed, input.record) !== input.record.blockFingerprint) {
+  if (!recordedBlockIsOwned(input.parsed, input.record, input.contribution)) {
     return { state: "conflict", reason: "foreign-edit" };
   }
   if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml

package/src/integrations/writer.ts

@@ -16,6 +16,7 @@ import { isLoopbackHostname } from "../codex/inject";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { fingerprint, canonicalContribution, fragmentPathsOf, type OwnershipRecord } from "./ownership";
+import { protectedContributionFingerprint, refreshablePathsOf } from "./ownership-policy";
 import { createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, type IntegrationClientId } from "./registry";
 import { classifyIntegration, exportContextOf } from "./state";
@@ -353,12 +354,17 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
     opId, clientId, kind: classified.state === "stale" ? "refresh" : "apply", at, configPath,
     snapshot, resultFingerprint: fingerprint(text), resultAbsent: false, priorRecord: record,
   };
+  const refreshablePaths = refreshablePathsOf(contribution);
   return commit({
     io, store, clientId, configPath, before, nextText: text, state: "current",
     priorRecord: record,
     record: {
       clientId, configPath, fileFingerprint: fingerprint(text),
       blockFingerprint: fingerprint(canonicalContribution(contribution)),
+      ...(refreshablePaths.length > 0 ? {
+        protectedBlockFingerprint: protectedContributionFingerprint(contribution, refreshablePaths),
+        refreshablePaths,
+      } : {}),
       fragmentPaths: fragmentPathsOf(contribution), createdContainers: created,
       appliedAt: at, opId,
     },

package/src/lib/azure-identity.ts

@@ -0,0 +1,154 @@
+import type { OcxProviderConfig } from "../types";
+
+export const AZURE_IDENTITY_SCOPE = "https://cognitiveservices.azure.com/.default";
+export const AZURE_IDENTITY_UNAVAILABLE_ERROR = "Azure identity credential unavailable";
+
+export interface AzureTokenCredential {
+  getToken(scope: string): Promise<{ token?: string } | null>;
+}
+
+export type AzureCredentialFactory = (options?: { managedIdentityClientId?: string }) =>
+  AzureTokenCredential | Promise<AzureTokenCredential>;
+export type AzureIdentityModuleLoader = () => Promise<{
+  DefaultAzureCredential: new (options?: { managedIdentityClientId?: string }) => AzureTokenCredential;
+}>;
+export type AzureLoggerModuleLoader = () => Promise<{
+  AzureLogger: { log: (...args: unknown[]) => void };
+}>;
+
+const credentials = new Map<string, AzureTokenCredential>();
+const inflight = new Map<string, Promise<AzureTokenCredential>>();
+const invalidatedInflight = new Set<Promise<AzureTokenCredential>>();
+let testFactory: AzureCredentialFactory | undefined;
+let testModuleLoader: AzureIdentityModuleLoader | undefined;
+let testLoggerModuleLoader: AzureLoggerModuleLoader | undefined;
+
+async function loadAzureLoggerModule(): Promise<{
+  AzureLogger: { log: (...args: unknown[]) => void };
+}> {
+  const packageName: string = "@azure/logger";
+  return await import(packageName) as unknown as {
+    AzureLogger: { log: (...args: unknown[]) => void };
+  };
+}
+
+async function suppressAzureSdkLogging(): Promise<void> {
+  const module = await (testLoggerModuleLoader ?? loadAzureLoggerModule)();
+  module.AzureLogger.log = () => {};
+}
+
+async function loadAzureIdentityModule(): Promise<{
+  DefaultAzureCredential: new (options?: { managedIdentityClientId?: string }) => AzureTokenCredential;
+}> {
+  // Keep the package out of the static module graph until Task 3 installs it.
+  const packageName: string = "@azure/identity";
+  return await import(packageName) as unknown as {
+    DefaultAzureCredential: new (options?: { managedIdentityClientId?: string }) => AzureTokenCredential;
+  };
+}
+
+async function loadDefaultAzureCredential(options?: { managedIdentityClientId?: string }): Promise<AzureTokenCredential> {
+  await suppressAzureSdkLogging();
+  const module = await (testModuleLoader ?? loadAzureIdentityModule)();
+  return options === undefined
+    ? new module.DefaultAzureCredential()
+    : new module.DefaultAzureCredential(options);
+}
+
+function clientIdFor(provider: OcxProviderConfig): string {
+  return provider.azureCredential?.managedIdentityClientId?.trim() ?? "";
+}
+
+async function credentialFor(clientId: string): Promise<AzureTokenCredential> {
+  const cached = credentials.get(clientId);
+  if (cached) return cached;
+  const running = inflight.get(clientId);
+  if (running) return running;
+  const generation = cacheGeneration;
+  let promise!: Promise<AzureTokenCredential>;
+  promise = Promise.resolve((testFactory ?? loadDefaultAzureCredential)(clientId ? { managedIdentityClientId: clientId } : undefined))
+    .then(credential => {
+      if (cacheGeneration === generation && !invalidatedInflight.has(promise)) {
+        credentials.set(clientId, credential);
+      }
+      return credential;
+    })
+    .finally(() => {
+      invalidatedInflight.delete(promise);
+      if (inflight.get(clientId) === promise) inflight.delete(clientId);
+    });
+  inflight.set(clientId, promise);
+  return promise;
+}
+
+export function azureIdentityClientId(provider: Pick<OcxProviderConfig, "azureCredential">): string | undefined {
+  if (provider.azureCredential?.type !== "default-azure-credential") return undefined;
+  return provider.azureCredential.managedIdentityClientId?.trim() ?? "";
+}
+
+export function invalidateAzureCredentialCache(clientId: string): void {
+  const key = clientId.trim();
+  const running = inflight.get(key);
+  if (running) invalidatedInflight.add(running);
+  credentials.delete(key);
+  inflight.delete(key);
+}
+
+export function __azureCredentialCacheStateForTests(): {
+  credentials: number;
+  inflight: number;
+  invalidatedInflight: number;
+} {
+  return {
+    credentials: credentials.size,
+    inflight: inflight.size,
+    invalidatedInflight: invalidatedInflight.size,
+  };
+}
+
+export async function getAzureAccessToken(provider: OcxProviderConfig): Promise<string> {
+  try {
+    const credential = await credentialFor(clientIdFor(provider));
+    const result = await credential.getToken(AZURE_IDENTITY_SCOPE);
+    const token = result?.token?.trim();
+    if (!token) throw new Error(AZURE_IDENTITY_UNAVAILABLE_ERROR);
+    return token;
+  } catch {
+    throw new Error(AZURE_IDENTITY_UNAVAILABLE_ERROR);
+  }
+}
+
+export function setAzureCredentialFactoryForTests(factory: AzureCredentialFactory): void {
+  cacheGeneration++;
+  testFactory = factory;
+  testModuleLoader = undefined;
+  testLoggerModuleLoader = undefined;
+  credentials.clear();
+  inflight.clear();
+  invalidatedInflight.clear();
+}
+
+export function __resetAzureCredentialCache(): void {
+  cacheGeneration++;
+  testFactory = undefined;
+  testModuleLoader = undefined;
+  testLoggerModuleLoader = undefined;
+  credentials.clear();
+  inflight.clear();
+  invalidatedInflight.clear();
+}
+
+let cacheGeneration = 0;
+
+export function setAzureIdentityModuleLoaderForTests(loader: AzureIdentityModuleLoader): void {
+  cacheGeneration++;
+  testFactory = undefined;
+  testModuleLoader = loader;
+  credentials.clear();
+  inflight.clear();
+  invalidatedInflight.clear();
+}
+
+export function setAzureLoggerModuleLoaderForTests(loader: AzureLoggerModuleLoader): void {
+  testLoggerModuleLoader = loader;
+}

package/src/lib/bounded-body.ts

@@ -103,6 +103,16 @@ function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, r
 	}
 }
 
+function cancelBodyWithoutWaiting(body: ReadableStream<Uint8Array>, reason?: unknown): void {
+	// A signal can already be aborted before a reader is attached. Still settle the
+	// original body so fetch-backed streams cannot retain a rejected read in that gap.
+	try {
+		void body.cancel(reason).catch(() => undefined);
+	} catch {
+		// A locked or non-conforming stream may throw synchronously from cancel().
+	}
+}
+
 /**
  * Consume the original response body as raw bytes under a strict memory ceiling.
  *
@@ -208,9 +218,11 @@ export async function readBoundedResponseBody(
 	options: BoundedBodyOptions = {},
 ): Promise<BoundedBodyResult> {
 	const signal = options.signal;
-	if (signal?.aborted) throw signal.reason;
-
 	const body = response.body;
+	if (signal?.aborted) {
+		if (body) cancelBodyWithoutWaiting(body, signal.reason);
+		throw signal.reason;
+	}
 	if (!body) {
 		return {
 			text: "",

package/src/lib/debug.ts

@@ -1,7 +1,10 @@
+import { createHmac, randomBytes } from "node:crypto";
 import { appendDebugLogLine } from "./debug-log-buffer";
 import { isDebugEnabled } from "./debug-settings";
 import { redactSecrets } from "./redact";
 
+let debugFingerprintKey: Uint8Array | undefined;
+
 function emitDebugLine(line: string): void {
   if (!isDebugEnabled()) return;
   try {
@@ -29,3 +32,42 @@ export function debugProviderDiagnostic(adapter: string, event: string, details:
     /* diagnostics must never affect request handling */
   }
 }
+
+/** Process-local, content-free correlation aid for opt-in provider diagnostics. */
+export function debugFingerprint(value: string | Uint8Array): string | undefined {
+  if (!isDebugEnabled()) return undefined;
+  try {
+    debugFingerprintKey ??= randomBytes(32);
+    return createHmac("sha256", debugFingerprintKey).update(value).digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
+export interface DebugStreamDiagnosticContext {
+  requestId: string;
+  adapterName: string;
+  attempt?: number;
+  recovery?: string;
+}
+
+export type DebugStreamDiagnosticStage = "adapter" | "bridge";
+
+/** Emit one structural line for an adapter/bridge event without retaining its content. */
+export function debugStreamDiagnostic(
+  context: DebugStreamDiagnosticContext,
+  stage: DebugStreamDiagnosticStage,
+  sequence: number,
+  eventType: string,
+  details?: Record<string, unknown>,
+): void {
+  debugProviderDiagnostic(context.adapterName, "stream", {
+    stage,
+    sequence,
+    eventType,
+    ...(context.requestId !== undefined ? { requestId: context.requestId } : {}),
+    ...(context.attempt !== undefined ? { attempt: context.attempt } : {}),
+    ...(context.recovery !== undefined ? { recovery: context.recovery } : {}),
+    ...details,
+  });
+}

package/src/lib/errors.ts

@@ -4,6 +4,16 @@ export interface OcxErrorPayload {
   code: string | null;
 }
 
+/** A local request validation failure that must remain a client-visible HTTP 400. */
+export class OcxRequestValidationError extends Error {
+  readonly status = 400;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "OcxRequestValidationError";
+  }
+}
+
 /** OpenAI / Codex hard block for high-risk cybersecurity activity (HTTP 400 or mid-stream). */
 export const CYBER_POLICY_ERROR_CODE = "cyber_policy";
 
@@ -180,6 +190,10 @@ export function classifyError(status: number, type: string, message: string): Oc
   }
   if (
     text.includes("insufficient_quota") ||
+    text.includes("insufficient credits") ||
+    text.includes("purchase more credits") ||
+    text.includes("run out of credits") ||
+    text.includes("out of credits") ||
     text.includes("exceeded your current quota") ||
     text.includes("quota exhausted") ||
     text.includes("account quota exceeded") ||

package/src/lib/process-control.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
-import { loadConfig, readRuntimePort } from "../config";
+import { loadConfig } from "../config";
+import { readRuntimePort } from "../config/process-state";
 import { configuredAdminToken } from "./admin-secrets";
 
 export function isProcessAlive(pid: number): boolean {