@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/server/responses/jev-model-invoke.ts

@@ -0,0 +1,190 @@
+import { readBoundedResponseBytes } from "../../lib/bounded-body";
+import { JevModelInvokeError, type JevModelInvoke, type JevModelInvokeResult } from "../../combos/jev-model-backend";
+import { JEV_MAX_REQUEST_BYTES, JEV_MAX_RESPONSE_BYTES } from "../../combos/jev";
+import type { OcxConfig } from "../../types";
+import { codexEffortRank, isCodexReasoningEffort } from "../../reasoning-effort";
+import { routeConcreteModel } from "../../router";
+import { supportedLadderFor } from "../effort-policy";
+import { createInferenceSendBudget } from "../inference/context";
+import { tryAdmitTurn } from "../lifecycle";
+import type { RequestLogContext } from "../request-log";
+import { createSseInspector } from "../relay";
+import type { HandleResponsesOptions } from "./core-options";
+
+type HandleResponses = (
+  req: Request,
+  config: OcxConfig,
+  logCtx: RequestLogContext,
+  options?: HandleResponsesOptions,
+) => Promise<Response>;
+
+export interface JevModelInvokerContext {
+  /** The request that owns the combo; only its spend root is reused, never its headers. */
+  req: Pick<Request, "headers">;
+  config: OcxConfig;
+  /** Parent options: only the typed admission scope and Codex auth policy cross over. */
+  options: Pick<HandleResponsesOptions, "admission" | "codexAuthPolicy">;
+  handleResponses: HandleResponses;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Concatenate assistant message text from a Responses output array. */
+function messageOutputText(output: unknown): string | undefined {
+  if (!Array.isArray(output)) return undefined;
+  const parts: string[] = [];
+  for (const item of output) {
+    if (!isRecord(item) || item.type !== "message" || !Array.isArray(item.content)) continue;
+    for (const part of item.content) {
+      if (isRecord(part) && part.type === "output_text" && typeof part.text === "string") parts.push(part.text);
+    }
+  }
+  return parts.length > 0 ? parts.join("") : undefined;
+}
+
+function responseUsage(response: Record<string, unknown>): Record<string, number> | undefined {
+  if (!isRecord(response.usage)) return undefined;
+  const usage: Record<string, number> = {};
+  for (const key of ["input_tokens", "output_tokens"] as const) {
+    const value = response.usage[key];
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) usage[key] = value;
+  }
+  return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+function terminalResult(response: Record<string, unknown>, deltaText: string): JevModelInvokeResult {
+  if (response.error !== undefined && response.error !== null) throw new JevModelInvokeError("http", "decision model failed");
+  if (response.status !== "completed") throw new JevModelInvokeError("malformed", "decision model did not complete");
+  const text = messageOutputText(response.output) ?? deltaText;
+  const usage = responseUsage(response);
+  return { text, ...(usage ? { usage } : {}) };
+}
+
+function decodeSse(bytes: Uint8Array): JevModelInvokeResult {
+  let completed: Record<string, unknown> | undefined;
+  let terminal: string | undefined;
+  let deltaText = "";
+  const inspector = createSseInspector({
+    onTerminal: status => { terminal ??= status; },
+    onCompletedResponse: value => { if (isRecord(value)) completed = value; },
+    onParsedPayload: payload => {
+      if (isRecord(payload) && payload.type === "response.output_text.delta" && typeof payload.delta === "string") {
+        deltaText += payload.delta;
+      }
+    },
+  });
+  try {
+    inspector.feed(bytes);
+    inspector.finish();
+  } finally {
+    inspector.dispose();
+  }
+  if (terminal !== "completed" || !completed) {
+    throw new JevModelInvokeError(terminal === "failed" ? "http" : "malformed", "decision model did not complete");
+  }
+  return terminalResult({ ...completed, status: completed.status ?? "completed" }, deltaText);
+}
+
+/**
+ * The answer is one short JSON object, so the decision turn carries its own output ceiling. It
+ * bounds billed output (including reasoning) and gives the spend reservation a nonzero ceiling;
+ * a truncated answer is malformed and fails open like any other bad reply.
+ */
+export const JEV_MODEL_MAX_OUTPUT_TOKENS = 1024;
+
+/**
+ * The cheapest reasoning effort the decision model declares, so a reasoning model cannot spend
+ * the whole output ceiling thinking before it writes the JSON answer. A model with no known
+ * ladder gets no reasoning field at all: some OpenAI-compatible servers reject one they do not
+ * support, and an unknown capability is not evidence that the field is safe to send.
+ */
+export function jevDecisionReasoningEffort(config: OcxConfig, model: string): string | undefined {
+  let ladder: string[] | undefined;
+  try {
+    const route = routeConcreteModel(config, model);
+    ladder = supportedLadderFor({ provider: route.provider, modelId: route.modelId });
+  } catch {
+    return undefined;
+  }
+  const rankable = (ladder ?? []).filter(isCodexReasoningEffort);
+  if (rankable.length === 0) return undefined;
+  if (rankable.includes("low")) return "low";
+  return rankable.reduce((lowest, effort) => (codexEffortRank(effort) < codexEffortRank(lowest) ? effort : lowest));
+}
+
+/**
+ * Build the invoker that runs one decision prompt as an internal Responses turn through the
+ * normal router. The decision request is its own logical request: a fresh turn lease and send
+ * budget, a detached log context whose spend tracker is settled here, and no caller credential
+ * or conversation header. It therefore runs on credentials configured on provider rows only.
+ */
+export function createJevModelInvoker(context: JevModelInvokerContext): JevModelInvoke {
+  return async ({ model, instructions, input, signal }) => {
+    const effort = jevDecisionReasoningEffort(context.config, model);
+    const body = JSON.stringify({
+      model,
+      stream: true,
+      store: false,
+      instructions,
+      input: [{ role: "user", content: [{ type: "input_text", text: input }] }],
+      tools: [],
+      max_output_tokens: JEV_MODEL_MAX_OUTPUT_TOKENS,
+      ...(effort ? { reasoning: { effort } } : {}),
+    });
+    if (new TextEncoder().encode(body).byteLength > JEV_MAX_REQUEST_BYTES) {
+      throw new JevModelInvokeError("malformed", "decision request too large");
+    }
+    const lease = tryAdmitTurn();
+    if (!lease) throw new JevModelInvokeError("network", "decision turn not admitted");
+    const childLog: RequestLogContext = { model, provider: "unknown", inboundProtocol: "responses" };
+    let usage: Record<string, number> | undefined;
+    try {
+      const request = new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        signal,
+      });
+      const response = await context.handleResponses(request, context.config, childLog, {
+        abortSignal: signal,
+        ...(context.options.admission ? { admission: context.options.admission } : {}),
+        ...(context.options.codexAuthPolicy ? { codexAuthPolicy: context.options.codexAuthPolicy } : {}),
+        // Explicit nulls: handleResponses captures caller credentials only when these are undefined.
+        callerDirectAuth: null,
+        openAiSidecarAuth: null,
+        nativeCallerAuth: null,
+        sendBudget: createInferenceSendBudget(context.req, childLog),
+        turnAdmissionLease: lease,
+        internalDecisionCall: true,
+      });
+      if (!response.ok) {
+        try { void response.body?.cancel().catch(() => undefined); } catch { /* best effort */ }
+        throw new JevModelInvokeError("http", `decision model returned ${response.status}`);
+      }
+      const bounded = await readBoundedResponseBytes(response, { maxBytes: JEV_MAX_RESPONSE_BYTES, signal });
+      if (bounded.oversized) throw new JevModelInvokeError("malformed", "decision response too large");
+      const result = response.headers.get("content-type")?.includes("text/event-stream")
+        ? decodeSse(bounded.bytes)
+        : (() => {
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bounded.bytes));
+          } catch {
+            throw new JevModelInvokeError("malformed", "decision response is not JSON");
+          }
+          if (!isRecord(parsed)) throw new JevModelInvokeError("malformed", "decision response is not an object");
+          return terminalResult(parsed, "");
+        })();
+      usage = result.usage;
+      return result;
+    } finally {
+      // No final log row is written for this detached context, so settle its spend here.
+      childLog.spendTracker?.settle(childLog.usage ?? (usage
+        ? { inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0 }
+        : undefined));
+      lease.release();
+    }
+  };
+}

package/src/server/responses/passthrough-delivery.ts

@@ -99,6 +99,7 @@ import {
   PLAINTEXT_V2_AGENT_MESSAGE_RESTORE_OVERFLOW_MESSAGE,
 } from "../../responses/plaintext-v2-agent-messages";
 import { createResponsesFieldBackfillBlockRewrite } from "./responses-field-backfill";
+import { createHostedImageDisplayRewrite, isLocalCodexImageClient } from "../responses-hosted-image-display";
 import { createResponsesFunctionToolRepairBlockRewrite } from "../responses-function-tool-repair";
 import {
   createUndeclaredToolCallGuardBlockRewrite,
@@ -840,6 +841,10 @@ export async function deliverPassthroughResponse(
           : undefined,
         createTerminalErrorRedactionBlockRewrite(nativeExchange.request.headers, maskCredential),
         rememberPlaintextBlock,
+        // Display-only projection must follow every continuation-cache observer.
+        isLocalCodexImageClient(req.headers, options.admission?.kind, options.inboundWire)
+          ? createHostedImageDisplayRewrite()
+          : undefined,
       ].filter((rewrite): rewrite is NonNullable<typeof rewrite> => rewrite !== undefined);
       const clientBlockRewrite = blockRewrites.length > 0
         ? composeSseBlockRewrites(...blockRewrites)
@@ -1318,6 +1323,17 @@ export async function deliverPassthroughResponse(
           JSON.parse(grokUpstreamEchoEnabled ? clientJson : text) as { id?: unknown; output?: unknown; status?: unknown; model?: unknown },
         );
       } catch { /* non-JSON despite content-type; recording is best-effort */ }
+      if (isLocalCodexImageClient(req.headers, options.admission?.kind, options.inboundWire)) {
+        const imageDisplay = createHostedImageDisplayRewrite();
+        try {
+          clientJson = imageDisplay.json(clientJson);
+        } catch (error) {
+          if (error instanceof RangeError) {
+            return formatErrorResponse(502, "upstream_error", "hosted image result count exceeds local display limit");
+          }
+          throw error;
+        } finally { imageDisplay.dispose?.(); }
+      }
       // #875: the transport-neutral reliability policy forced a bounded JSON
       // upstream for a client that asked for SSE. Reframe the completed JSON
       // as the canonical terminal SSE sequence (created → output_item.done →

package/src/server/responses/policy-fallback.ts

@@ -11,6 +11,8 @@ import { captureExplicitOpenAiCallerAuth } from "../../providers/openai-sidecar"
 import { captureCallerDirectAuth } from "../../providers/caller-authorization";
 import { resolvePolicyProfileId } from "../../routing/profile";
 import { parseSyntheticRowId } from "../fast-row";
+import { routeConcreteModel } from "../../router";
+import { isPolicyCandidateRefusal, policyWireDestination, type PolicyRequestScope } from "./policy-request-scope";
 
 type CoreHandler = typeof handleResponsesCore;
 type CoreOptions = Parameters<CoreHandler>[3];
@@ -23,6 +25,25 @@ function candidateKey(candidate: Pick<RouteCandidateTrace, "provider" | "model">
   return `${candidate.provider}\u0000${candidate.model}`;
 }
 
+function staysWithinPolicyAfterRedirect(
+  config: OcxConfig,
+  policyEligibility: ReadonlySet<string>,
+  candidate: RouteCandidateTrace,
+  triedDestinations: ReadonlySet<string>,
+): boolean {
+  try {
+    // Both inspection and execution resolve the original concrete candidate, without public
+    // combo/profile aliases or combo selection writes. A redirect must remain in the evaluation.
+    const routed = routeConcreteModel(config, `${candidate.provider}/${candidate.model}`);
+    return policyEligibility.has(`${routed.providerName}\u0000${routed.modelId}`)
+      && !triedDestinations.has(policyWireDestination(routed));
+  } catch {
+    // A route that fails to resolve (e.g. a redirect cycle) cannot succeed on retry; its terminal
+    // error is rarely hop-worthy, so keep the fallback alive for the next eligible candidate.
+    return false;
+  }
+}
+
 /**
  * Rank the remaining candidates from the ORIGINAL policy trace. The initial
  * decision stays immutable; fallback execution belongs in attempts[], not in a
@@ -87,6 +108,7 @@ async function shouldHopPolicyCandidate(response: Response, signal?: AbortSignal
   if (response.status < 400 || signal?.aborted) return false;
   // A response that must not be sent again cannot open a policy-candidate retry either.
   if (isNonReplayableResponse(response)) return false;
+  if (isPolicyCandidateRefusal(response)) return true;
   try {
     const inspected = await readBoundedResponseBody(response.clone(), { signal });
     const text = inspected.displaySafe ? inspected.text : "";
@@ -131,11 +153,13 @@ export async function handleResponsesWithPolicyFallback(
   deps: PolicyFallbackDeps = {},
 ): Promise<Response> {
   const runCore = deps.runCore ?? handleResponsesCore;
+  const policyScope: PolicyRequestScope = options.policyRequestScope ?? { triedDestinations: new Set() };
   let requestBodyReadNotified = false;
   let storedPool401ReplayDispatched = false;
   let rawBody: Record<string, unknown> | null = null;
   const coreOptions: CoreOptions = {
     ...options,
+    policyRequestScope: policyScope,
     openAiSidecarAuth: options.openAiSidecarAuth === undefined
       ? captureExplicitOpenAiCallerAuth(req.headers, config) : options.openAiSidecarAuth,
     nativeCallerAuth: options.nativeCallerAuth === undefined
@@ -175,25 +199,52 @@ export async function handleResponsesWithPolicyFallback(
     if (overload) return overload;
     throw error;
   }
-  const initialTrace = logCtx.routeDecision;
+  const initialTrace = policyScope.decision ?? logCtx.routeDecision;
   const initialRequestedModel = logCtx.requestedModel;
   if (!rawBody || !isPolicyDecision(initialTrace)) return response;
 
   const tried = new Set<string>([
     candidateKey({ provider: initialTrace.selected.provider, model: initialTrace.selected.model }),
   ]);
+  const selectedCandidate = initialTrace.selected.candidateIndex === undefined ? undefined
+    : initialTrace.candidates[initialTrace.selected.candidateIndex];
+  if (selectedCandidate) tried.add(candidateKey(selectedCandidate));
+  // Redirect eligibility needs the full evaluation membership, not the bounded trace list.
+  const policyEligibility: ReadonlySet<string> = policyScope.eligibility ?? logCtx.policyEligibility
+    ?? new Set(initialTrace.candidates
+      .filter(candidate => candidate.eligible)
+      .map(candidate => candidateKey(candidate)));
+  policyScope.eligibility = policyEligibility;
+  policyScope.decision = initialTrace;
+  policyScope.triedDestinations.add(policyScope.preparedDestination ?? policyWireDestination({
+    providerName: initialTrace.selected.provider, modelId: initialTrace.selected.model,
+  }));
 
   while (!storedPool401ReplayDispatched && await shouldHopPolicyCandidate(response, req.signal)) {
     if (req.signal.aborted) return response;
-    const next = rankPolicyFallbackCandidates(initialTrace, tried)[0];
+    const next = rankPolicyFallbackCandidates(initialTrace, tried)
+      .find(candidate => staysWithinPolicyAfterRedirect(config, policyEligibility, candidate, policyScope.triedDestinations));
     if (!next) return response;
     tried.add(candidateKey(next));
 
+    // Retain the failed response's log owner until a candidate actually replaces it. This is
+    // deliberately shallow: completed attempts and the live spend tracker keep their identity.
+    const failureLog = { ...logCtx };
     finishFailedPolicyAttempt(logCtx, response.status);
     const retryRequest = requestWithCandidate(req, rawBody, next);
+    delete policyScope.preparedDestination;
     try {
       try {
-        response = await runCore(retryRequest, config, logCtx, coreOptions);
+        const nextResponse = await runCore(retryRequest, config, logCtx, { ...coreOptions, policyFallbackCandidate: next });
+        // A locally skipped route owns neither the returned failure nor its usage/settlement.
+        // Preparation can replace route metadata and the tracker, or add fields absent before it.
+        if (isPolicyCandidateRefusal(nextResponse)) {
+          for (const key of Object.keys(logCtx)) {
+            if (!Object.hasOwn(failureLog, key)) Reflect.deleteProperty(logCtx, key);
+          }
+          Object.assign(logCtx, failureLog);
+        } else response = nextResponse;
+        if (policyScope.preparedDestination) policyScope.triedDestinations.add(policyScope.preparedDestination);
       } catch (error) {
         const overload = requestPacingOverloadResponse(error);
         if (overload) return overload;
@@ -202,6 +253,7 @@ export async function handleResponsesWithPolicyFallback(
     } finally {
       logCtx.requestedModel = initialRequestedModel;
       logCtx.routeDecision = initialTrace;
+      logCtx.policyEligibility = policyEligibility;
     }
   }
 

package/src/server/responses/policy-request-scope.ts

@@ -0,0 +1,80 @@
+import { formatErrorResponse } from "../../bridge";
+import type { RouteResult } from "../../router";
+import type { RouteDecisionTraceV1 } from "../../routing/trace";
+import { resolveOpenAiVirtualModel } from "../../providers/openai-virtual-models";
+
+/** Request-owned authorization, separate from the diagnostic trace and each physical attempt. */
+export interface PolicyRequestScope {
+  decision?: RouteDecisionTraceV1;
+  eligibility?: ReadonlySet<string>;
+  readonly triedDestinations: Set<string>;
+  preparedDestination?: string;
+}
+
+export function policyDestinationKey(provider: string, model: string): string {
+  return `${provider}\u0000${model}`;
+}
+
+export function policyWireDestination(route: Pick<RouteResult, "providerName" | "modelId">): string {
+  const model = resolveOpenAiVirtualModel(route.providerName, route.modelId)?.wireModelId ?? route.modelId;
+  return policyDestinationKey(route.providerName, model);
+}
+
+export class PolicyCandidateUnavailableError extends Error {
+  constructor() {
+    super("The candidate cannot serve this request within its original routing policy.");
+    this.name = "PolicyCandidateUnavailableError";
+  }
+}
+
+const localRefusals = new WeakSet<Response>();
+
+export function policyCandidateRefusalResponse(error: unknown): Response | undefined {
+  if (!(error instanceof PolicyCandidateUnavailableError)) return undefined;
+  const response = formatErrorResponse(409, "policy_candidate_unavailable", error.message);
+  localRefusals.add(response);
+  return response;
+}
+
+/** Upstream text or a matching error code cannot authorize another policy attempt. */
+export function isPolicyCandidateRefusal(response: Response): boolean {
+  return localRefusals.has(response);
+}
+
+export function capturePolicyRequestRoute(scope: PolicyRequestScope, route: RouteResult): RouteResult {
+  if (!scope.eligibility && route.policyEligibility && route.routeDecision?.routeKind === "policy") {
+    scope.eligibility = new Set(route.policyEligibility);
+    scope.decision = route.routeDecision;
+  }
+  if (!scope.eligibility) return route;
+  if (!scope.eligibility.has(policyDestinationKey(route.providerName, route.modelId))) {
+    throw new PolicyCandidateUnavailableError();
+  }
+  // Preparation and normalization both project from RouteResult into the log. Keep the original
+  // authorization and decision on every allowed replacement, including recovery's second pass.
+  route.routeKind = "policy";
+  route.policyEligibility = scope.eligibility;
+  route.routeDecision = scope.decision;
+  return route;
+}
+
+/** Only the admitted selector's existing virtual-model rewrite may change its final route id. */
+export function assertPolicyNormalizedRoute(
+  scope: PolicyRequestScope,
+  admitted: Pick<RouteResult, "providerName" | "modelId">,
+  route: RouteResult,
+): void {
+  if (!scope.eligibility) return;
+  if (route.providerName !== admitted.providerName || (route.modelId !== admitted.modelId
+    && route.modelId !== resolveOpenAiVirtualModel(admitted.providerName, admitted.modelId)?.wireModelId)) {
+    throw new PolicyCandidateUnavailableError();
+  }
+}
+
+/** Called once preparation has settled the wire, before dispatch; account retries keep their own budget. */
+export function recordPolicyPreparedDestination(scope: PolicyRequestScope, provider: string, model: string): void {
+  if (!scope.eligibility) return;
+  const destination = policyDestinationKey(provider, model);
+  if (scope.triedDestinations.has(destination)) throw new PolicyCandidateUnavailableError();
+  scope.preparedDestination = destination;
+}