@bitkyc08/opencodex 2.19.0 → 2.21.0

package/src/server/responses/empty-completion-guard.ts

@@ -0,0 +1,276 @@
+import type { AdapterEvent, OcxConfig, OcxUsage } from "../../types";
+
+/**
+ * Empty-completion guard for Responses turns (port of codex-router's
+ * empty-completion-guard + single retry, PR #145).
+ *
+ * Failure mode: the upstream answers 200 and completes the turn but never
+ * produced output text or a tool call (a reasoning-only stream that ends with
+ * nothing is the canonical shape). The client has no code path for "the model
+ * said nothing", so it silently records the turn as done — the "random stop"
+ * nobody can explain. The guard holds pre-content events (reasoning deltas
+ * are deliberately NOT content), and when a terminal event arrives with no
+ * content it suppresses the terminal and retries the IDENTICAL turn once
+ * (same request bytes, same headers). If the retry is also empty — or fails
+ * upstream — the client sees a stated failure instead of a second silent
+ * success.
+ *
+ * The retry is explicitly enabled by top-level config. The environment switch
+ * is a disable-only emergency override: OCX_EMPTY_COMPLETION_RETRY=0 restores
+ * the previous relay behavior without editing the persisted config.
+ */
+export const EMPTY_COMPLETION_RETRY_ENV = "OCX_EMPTY_COMPLETION_RETRY";
+
+/** Retained pre-content events are bounded independently by count and encoded size. */
+export const EMPTY_COMPLETION_MAX_BUFFERED_EVENTS = 1_024;
+export const EMPTY_COMPLETION_MAX_BUFFERED_BYTES = 1_048_576;
+
+export function emptyCompletionRetryEnabled(
+  config: Pick<OcxConfig, "emptyCompletionRetry">,
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  return config.emptyCompletionRetry === true && env[EMPTY_COMPLETION_RETRY_ENV] !== "0";
+}
+
+/** Surfaced when the single retry was also empty or failed upstream. */
+export const EMPTY_COMPLETION_RETRY_FAILED_CODE = "empty_completion_retry_failed";
+
+/**
+ * Terminal stop reasons the bridge renders as a visible `response.incomplete`
+ * (max_tokens / content_filter). Those are already a stated failure, not the
+ * silent empty success this guard exists to catch, and retrying the identical
+ * request would burn tokens for the same truncated result.
+ */
+const VISIBLE_INCOMPLETE_STOP_REASONS = new Set(["max_tokens", "content_filter"]);
+const UTF8_ENCODER = new TextEncoder();
+
+function retainedEventBytes(event: AdapterEvent): number {
+  return UTF8_ENCODER.encode(JSON.stringify(event)).byteLength;
+}
+
+function isReasoningEvent(event: AdapterEvent): boolean {
+  return event.type === "thinking_delta"
+    || event.type === "thinking_signature"
+    || event.type === "redacted_thinking"
+    || event.type === "kiro_redacted_reasoning"
+    || event.type === "reasoning_raw_delta";
+}
+
+function isTerminalEvent(
+  event: AdapterEvent,
+): event is Extract<AdapterEvent, { type: "done" | "incomplete" | "error" }> {
+  return event.type === "done" || event.type === "incomplete" || event.type === "error";
+}
+
+/**
+ * Content means something the client can act on: output text or a tool call
+ * (web-search cells included). Reasoning deltas are deliberately not content —
+ * a turn that streams only reasoning and then completes with nothing is
+ * exactly the empty completion this guard exists to catch. Empty text deltas
+ * (some batch adapters always carry `""`) are not content either.
+ */
+export function isContentEvent(event: AdapterEvent): boolean {
+  switch (event.type) {
+    case "text_delta":
+      return event.text.length > 0;
+    case "tool_call_start":
+    case "tool_call_delta":
+    case "tool_call_end":
+    case "web_search_call_begin":
+    case "web_search_call_end":
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function emptyCompletionRetryFailedEvent(
+  usage?: OcxUsage,
+  retryFailedUpstream = false,
+): Extract<AdapterEvent, { type: "error" }> {
+  return {
+    type: "error",
+    status: 502,
+    errorType: "upstream_error",
+    code: EMPTY_COMPLETION_RETRY_FAILED_CODE,
+    message: retryFailedUpstream
+      ? "The model returned an empty completion and the retry failed upstream."
+      : "The model returned an empty completion. opencodex retried once and the completion was empty again.",
+    ...(usage ? { usage } : {}),
+  };
+}
+
+/**
+ * Sum two usage snapshots. Same semantics as terminal-guard's mergeUsage and
+ * request-log's aggregateAttemptUsage: token totals add across the attempts;
+ * `estimated` wins when either attempt only estimated.
+ */
+export function mergeUsage(
+  first: OcxUsage | undefined,
+  second: OcxUsage | undefined,
+): OcxUsage | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  const sumOptional = (key: keyof OcxUsage): number | undefined => {
+    const left = first[key];
+    const right = second[key];
+    return typeof left === "number" || typeof right === "number"
+      ? (typeof left === "number" ? left : 0) + (typeof right === "number" ? right : 0)
+      : undefined;
+  };
+  const cachedInputTokens = sumOptional("cachedInputTokens");
+  const cacheReadInputTokens = sumOptional("cacheReadInputTokens");
+  const cacheCreationInputTokens = sumOptional("cacheCreationInputTokens");
+  const reasoningOutputTokens = sumOptional("reasoningOutputTokens");
+  const contextTotalTokens = second.contextTotalTokens ?? first.contextTotalTokens;
+  const inputTokens = first.inputTokens + second.inputTokens;
+  const outputTokens = first.outputTokens + second.outputTokens;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    ...(contextTotalTokens !== undefined ? { contextTotalTokens } : {}),
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+    ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+    ...(reasoningOutputTokens !== undefined ? { reasoningOutputTokens } : {}),
+    ...(first.estimated || second.estimated ? { estimated: true } : {}),
+  };
+}
+
+export interface EmptyCompletionGuardOptions {
+  firstEvents: AsyncIterable<AdapterEvent>;
+  /**
+   * Re-run the IDENTICAL turn: same request body, same headers, same signal.
+   * Receives no arguments — the request must not be modified between attempts.
+   */
+  continuation: () => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+  /** How many times an empty completion is retried; default 1 (the router's single retry). */
+  maxRetries?: number;
+}
+
+/**
+ * Watch an adapter event stream for the empty-completion failure mode. Events
+ * are held until the turn produces content or ends: reasoning and other
+ * pre-content events stay buffered (released in order on first content), the
+ * terminal is withheld, and an empty terminal triggers one identical-turn
+ * retry through `continuation`. Usage is merged across attempts so the bridge
+ * and request log meter the whole turn, not just the attempt that succeeded.
+ *
+ * Heartbeats always pass through untouched: they feed the bridge's stall
+ * watchdog, so holding them behind the content gate would trip false
+ * upstream_stall_timeout failures on slow reasoning-only turns.
+ */
+export async function* guardEmptyCompletionEventStream(
+  options: EmptyCompletionGuardOptions,
+): AsyncGenerator<AdapterEvent> {
+  const maxRetries = Math.max(0, Math.floor(options.maxRetries ?? 1));
+  let source = options.firstEvents;
+  let held: AdapterEvent[] = [];
+  let heldBytes = 0;
+  let sawContent = false;
+  let passthrough = false;
+  let retries = 0;
+  let usage: OcxUsage | undefined;
+
+  const withUsage = (event: AdapterEvent & { usage?: OcxUsage }): AdapterEvent => {
+    const merged = mergeUsage(usage, event.usage);
+    return merged ? { ...event, ...(merged ? { usage: merged } : {}) } : event;
+  };
+  const releaseHeld = (): AdapterEvent[] => {
+    const released = held;
+    held = [];
+    heldBytes = 0;
+    return released;
+  };
+
+  while (true) {
+    let terminalSeen = false;
+    for await (const event of source) {
+      if (event.type === "heartbeat") {
+        yield event;
+        continue;
+      }
+      if (sawContent || passthrough) {
+        // Buffered content is already flowing; everything downstream passes
+        // through. Every terminal carries usage merged across every attempt.
+        yield isTerminalEvent(event) ? withUsage(event) : event;
+        continue;
+      }
+      if (isContentEvent(event)) {
+        sawContent = true;
+        yield* releaseHeld();
+        yield event;
+        continue;
+      }
+      if (event.type === "done") {
+        usage = mergeUsage(usage, event.usage);
+        if (event.stopReason !== undefined && VISIBLE_INCOMPLETE_STOP_REASONS.has(event.stopReason)) {
+          // Rendered as response.incomplete: a stated failure, not the silent
+          // empty success this guard exists to catch.
+          yield* releaseHeld();
+          yield { ...event, ...(usage ? { usage } : {}) };
+          return;
+        }
+        if (retries < maxRetries) {
+          // Suppress the terminal: the client must never see a completed event
+          // for a turn that produced nothing. Retry the identical turn.
+          retries += 1;
+          try {
+            source = await options.continuation();
+          } catch {
+            yield emptyCompletionRetryFailedEvent(usage, true);
+            return;
+          }
+          terminalSeen = true;
+          break;
+        }
+        // The retry was also empty: a stated failure, not a second silent
+        // success.
+        yield emptyCompletionRetryFailedEvent(usage);
+        return;
+      }
+      if (event.type === "error") {
+        if (retries > 0 && event.status !== 499) {
+          // The retry failed upstream. Its body cannot reach the client (the
+          // 200 head went out with the first attempt), so state the failure in
+          // the stream's own error framing — same move as the router's
+          // empty_completion_retry_failed. Client cancels (499) pass through.
+          yield emptyCompletionRetryFailedEvent(mergeUsage(usage, event.usage), true);
+          return;
+        }
+        yield* releaseHeld();
+        yield withUsage(event);
+        return;
+      }
+      if (event.type === "incomplete") {
+        // A structured incomplete is already a visible failure; never convert
+        // it into an empty completion.
+        yield* releaseHeld();
+        yield withUsage(event);
+        return;
+      }
+      const eventBytes = retainedEventBytes(event);
+      if (held.length + 1 > EMPTY_COMPLETION_MAX_BUFFERED_EVENTS
+        || heldBytes + eventBytes > EMPTY_COMPLETION_MAX_BUFFERED_BYTES) {
+        // Preserve data rather than retaining without bound: release the prefix,
+        // emit this event, and stop attempting an empty-completion retry for the turn.
+        yield* releaseHeld();
+        yield event;
+        passthrough = true;
+        continue;
+      }
+      held.push(event);
+      heldBytes += eventBytes;
+      // The bridge watchdog sees only yielded events. Feed it while reasoning is
+      // held so a long reasoning-only prefix remains live without exposing it early.
+      if (isReasoningEvent(event)) yield { type: "heartbeat" };
+    }
+    if (!terminalSeen) {
+      // The source ended without a terminal event (truncated stream). Release
+      // what was held so the bridge can mark the stream incomplete.
+      yield* releaseHeld();
+      return;
+    }
+  }
+}

package/src/server/responses/fetch-helpers.ts

@@ -102,6 +102,7 @@ import {
 } from "../relay";
 import { hasResponsesItemIdRepair, relaySseWithResponsesItemIdRepair } from "../responses-item-id-repair";
 import type { EffectiveSubagentRoster, SpawnAgentSurface } from "../../codex/catalog";
+import { waitForProviderRequestSlot } from "../../providers/request-pacing";
 
 
 export function disableResponsesRequestTimeout(req: Request, server: Pick<Server<WsData>, "timeout"> | undefined): boolean {
@@ -136,21 +137,48 @@ export function safeOriginLabel(url: string): string {
 
 
 
+export interface PaceAwareFetch {
+  waitForPacing?: (signal?: AbortSignal) => Promise<void>;
+  unpacedFetch?: typeof globalThis.fetch;
+}
+
+export type ProviderFetch = typeof globalThis.fetch & PaceAwareFetch;
+
+export interface ProviderFetchOptions {
+  providerName?: string;
+  modelId?: string;
+}
+
 export function providerFetch(
   provider: OcxProviderConfig,
   runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
-): typeof globalThis.fetch {
+  options: ProviderFetchOptions = {},
+): ProviderFetch {
   const base = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
   // ChatGPT Codex backend: streaming turns ride the responses_websockets
   // transport (measured ~3s faster TTFT than the SSE POST queue); everything
   // else keeps the provider's HTTP fetch. See ws-upstream.ts for the details.
-  const wrapped = (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+  const unpaced = async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
     if (typeof input === "string" && init && shouldUseCodexWsUpstream(input, init, runtime)) {
       return codexWsUpstreamFetch(input, init, base, runtime);
     }
     return base(input, init);
   };
-  return wrapped as typeof globalThis.fetch;
+  const waitForPacing = (signal?: AbortSignal) => options.providerName
+    ? waitForProviderRequestSlot(options.providerName, provider, options.modelId, signal)
+    : Promise.resolve();
+  const wrapped = async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+    await waitForPacing(init?.signal ?? undefined);
+    return unpaced(input, init);
+  };
+  const preconnect = (...args: Parameters<typeof globalThis.fetch.preconnect>): void => {
+    base.preconnect?.(...args);
+  };
+  return Object.assign(wrapped, {
+    preconnect,
+    waitForPacing,
+    unpacedFetch: Object.assign(unpaced, { preconnect }),
+  });
 }
 
 
@@ -164,6 +192,9 @@ export async function fetchWithHeaderTimeout(
   executor: typeof globalThis.fetch = globalThis.fetch,
   manualRedirect = false,
 ): Promise<Response> {
+  const pacing = executor as ProviderFetch;
+  await pacing.waitForPacing?.(abortSignal);
+  const fetchExecutor = pacing.unpacedFetch ?? executor;
   const timeout = new AbortController();
   const timer = setTimeout(() => {
     if (!timeout.signal.aborted) timeout.abort(new DOMException("Timeout elapsed", "TimeoutError"));
@@ -175,7 +206,7 @@ export async function fetchWithHeaderTimeout(
     headers.set("accept-encoding", "identity");
   }
   try {
-    return await executor(url, {
+    return await fetchExecutor(url, {
       ...init,
       headers,
       // Credential-bearing sends opt into manual redirects so a 3xx is relayed

package/src/server/responses/pacing-overload.ts

@@ -0,0 +1,13 @@
+import { formatErrorResponse } from "../../bridge";
+import { RequestPacingQueueOverloadError } from "../../providers/request-pacing";
+
+/** Convert local request-pacing admission failures into a retryable HTTP response. */
+export function requestPacingOverloadResponse(error: unknown): Response | undefined {
+  if (!(error instanceof RequestPacingQueueOverloadError)) return undefined;
+  return formatErrorResponse(
+    429,
+    "rate_limit_error",
+    error.message,
+    { retryAfter: String(error.retryAfterSeconds) },
+  );
+}

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

@@ -5,6 +5,7 @@ import { finishRequestAttempt, type RequestLogContext } from "../request-log";
 import type { OcxConfig } from "../../types";
 import type { RouteCandidateTrace, RouteDecisionTraceV1 } from "../../routing/trace";
 import { handleResponses as handleResponsesCore } from "./core";
+import { requestPacingOverloadResponse } from "./pacing-overload";
 
 type CoreHandler = typeof handleResponsesCore;
 type CoreOptions = Parameters<CoreHandler>[3];
@@ -133,7 +134,14 @@ export async function handleResponsesWithPolicyFallback(
     // Core owns the client-facing parse/decompression error.
   }
 
-  let response = await runCore(req, config, logCtx, coreOptions);
+  let response: Response;
+  try {
+    response = await runCore(req, config, logCtx, coreOptions);
+  } catch (error) {
+    const overload = requestPacingOverloadResponse(error);
+    if (overload) return overload;
+    throw error;
+  }
   const initialTrace = logCtx.routeDecision;
   const initialRequestedModel = logCtx.requestedModel;
   if (!rawBody || !isPolicyDecision(initialTrace)) return response;
@@ -151,7 +159,13 @@ export async function handleResponsesWithPolicyFallback(
     finishFailedPolicyAttempt(logCtx, response.status);
     const retryRequest = requestWithCandidate(req, rawBody, next);
     try {
-      response = await runCore(retryRequest, config, logCtx, coreOptions);
+      try {
+        response = await runCore(retryRequest, config, logCtx, coreOptions);
+      } catch (error) {
+        const overload = requestPacingOverloadResponse(error);
+        if (overload) return overload;
+        throw error;
+      }
     } finally {
       logCtx.requestedModel = initialRequestedModel;
       logCtx.routeDecision = initialTrace;

package/src/server/responses/terminal-guard.ts

@@ -195,7 +195,7 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
     for await (const event of source) {
       if (event.type === "done") {
         terminalSeen = true;
-        const analysis = options.adapterName === "anthropic"
+        const analysis = (options.adapterName === "anthropic" || options.adapterName === "openai-chat")
           ? analyzeTerminalTurn(parsed, seen)
           : { decision: "pass" as const };
         const normalStop = event.stopReason !== "max_tokens" && event.stopReason !== "content_filter";

package/src/server/responses/upstream-error.ts

@@ -5,7 +5,12 @@
  * #553 looking for an adapter URL bug that does not exist. Name the likely cause and the
  * command that settles it.
  */
+import { RequestPacingQueueOverloadError } from "../../providers/request-pacing";
+
 export function describeUpstreamConnectFailure(err: unknown, connectMs: number): string {
+  // Local pacing admission is not a transport failure. Let the outer response boundary
+  // preserve its retryable 429 identity instead of laundering it into a 502.
+  if (err instanceof RequestPacingQueueOverloadError) throw err;
   if (err instanceof Error && err.name === "TimeoutError") {
     return `Provider connect timeout after ${connectMs}ms`;
   }

package/src/server/responses.ts

@@ -1,10 +1,25 @@
 // AUTO-SPLIT facade: original responses.ts body moved into ./responses/* modules.
 // Public surface preserved exactly; importers keep using "src/server/responses".
+import { handleResponsesCompact as handleResponsesCompactImpl } from "./responses/compact";
+import { requestPacingOverloadResponse } from "./responses/pacing-overload";
+
 export { buildToolBridgeMaps, isV1CollabSurface, collabSurface, multiAgentGuidanceText, V2_GUIDANCE_CHAR_BUDGET, injectDeveloperMessage } from "./responses/collaboration";
 export type { MultiAgentGuidanceOptions, MultiAgentGuidanceDeps } from "./responses/collaboration";
 export { hasUnreadableEncryptedAgentTask, sanitizeEncryptedContentInPlace } from "./responses/encrypted-payload";
-export { COMPACT_RESPONSE_MAX_BYTES, bufferCompactResponse, handleResponsesCompact } from "./responses/compact";
+export { COMPACT_RESPONSE_MAX_BYTES, bufferCompactResponse } from "./responses/compact";
 export { disableResponsesRequestTimeout, safeHostLabel, fetchWithHeaderTimeout } from "./responses/fetch-helpers";
 export { sidecarOutcomeRecorder, isShadowSourceModel, codexLogAccountId, usesCodexForwardPoolAuth, codexForwardTerminalOutcomeRecorder, decodeRequestErrorResponse, buildComboChildHeaders, linkAbortSignal } from "./responses/core";
 export { handleResponses, handleResponsesWithPolicyFallback, rankPolicyFallbackCandidates } from "./responses/policy-fallback";
-export { adapterNeedsForcedContinuation } from "./responses/core";
+export { adapterNeedsForcedContinuation } from "./responses/core";
+
+export async function handleResponsesCompact(
+  ...args: Parameters<typeof handleResponsesCompactImpl>
+): Promise<Response> {
+  try {
+    return await handleResponsesCompactImpl(...args);
+  } catch (error) {
+    const overload = requestPacingOverloadResponse(error);
+    if (overload) return overload;
+    throw error;
+  }
+}

package/src/server/system-env.ts

@@ -335,7 +335,7 @@ export async function injectSystemEnv(port: number, config: OcxConfig): Promise<
     // without a token — keep it in sync with this proxy's /v1/models. Best-effort.
     try {
       const { refreshGatewayModelCacheFromProxy } = await import("../claude/gateway-cache");
-      await refreshGatewayModelCacheFromProxy(port);
+      await refreshGatewayModelCacheFromProxy(port, { admissionConfig: config });
     } catch { /* best-effort */ }
 
     // Roster agent definitions (devlog 070): same launch-time sync for plain `claude`.

package/src/types.ts

@@ -180,10 +180,27 @@ export interface OcxToolCall {
   arguments: Record<string, unknown>;
   customWireName?: string;
   thoughtSignature?: string;
+  /**
+   * Provider-issued opaque metadata that must survive the whole round trip unchanged
+   * (issue #1735). A signed Gemini part is only valid when its signature comes back on the
+   * SAME part it was issued for, so this travels with the individual tool call rather than
+   * being matched by name/arguments after the fact.
+   */
+  providerMetadata?: OcxProviderOpaqueToolCallMetadata;
   /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
   namespace?: string;
 }
 
+/**
+ * Opaque, provider-scoped tool-call metadata. Values are never parsed, merged, re-encoded, or
+ * synthesized — they are carried verbatim or not at all.
+ */
+export interface OcxProviderOpaqueToolCallMetadata {
+  google?: {
+    thoughtSignature?: string;
+  };
+}
+
 export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
 
 export interface OcxTool {
@@ -328,7 +345,7 @@ export type AdapterEvent =
   // Never rendered — it only rides the reasoning item's envelope so the next request can replay it.
   | { type: "kiro_redacted_reasoning"; data: string }
   | { type: "reasoning_raw_delta"; text: string }
-  | { type: "tool_call_start"; id: string; name: string }
+  | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata }
   | { type: "tool_call_delta"; arguments: string }
   | { type: "tool_call_end" }
   /** Internal boundary between a guarded first pass and its one-shot continuation. */
@@ -587,6 +604,13 @@ export interface OcxCustomModel {
   contextWindow?: number;
   /** 입력 모달리티 (선택, 기본 ["text"]) */
   inputModalities?: string[];
+  /**
+   * Reasoning ladder (Codex labels) this custom row explicitly advertises. An empty array
+   * hides the effort control; an omitted key leaves the provider-derived ladder in charge.
+   */
+  reasoningEfforts?: string[];
+  /** Default effort label when `reasoningEfforts` is non-empty. */
+  defaultReasoningEffort?: string;
   /** 추가 시각 (ISO 8601) */
   addedAt?: string;
 }
@@ -623,6 +647,8 @@ export interface OcxClientIntegrationsConfig {
 
 export interface OcxConfig {
   port: number;
+  /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
+  emptyCompletionRetry?: boolean;
   /** Maximum usage-log bytes read for one management snapshot. */
   managementUsageMaxReadBytes?: number;
   providers: Record<string, OcxProviderConfig>;
@@ -645,6 +671,20 @@ export interface OcxConfig {
    * into a selector-qualified group; Codex still advertises only the first 5 visible rows.
    */
   subagentModels?: string[];
+  /**
+   * Optional full picker ordering for the Codex model catalog, independent of the
+   * 5-slot `subagentModels` spawn_agent cap. DISPLAY-ONLY: it controls the visual order of
+   * the Codex model picker for large routed catalogs (10-20+ models) that would otherwise sort
+   * arbitrarily and reshuffle on every rebuild. Values are routed `<provider>/<model>` catalog
+   * slugs (matched by exact slug or `provider/id`); native OpenAI passthrough rows and
+   * account-qualified native rows are not reordered (order native rows via `subagentModels`).
+   * Listed routed rows appear in array order; rows not listed keep their normal display order.
+   * `subagentModels`-featured rows keep their top position. When unset or empty, catalog
+   * priority is unchanged. This changes ONLY what the user sees in the picker: the spawn_agent
+   * candidate set is derived from each row's natural priority and is provably unaffected, even
+   * when every routed row is listed (see opencodex_spawn_priority / effectiveSubagentRoster).
+   */
+  modelPickerOrder?: string[];
   /**
    * Priority-ordered fallback models for spawned sub-agents. When the requested
    * model is quota-exhausted or recently failed, opencodex rewrites the child
@@ -966,6 +1006,12 @@ export interface OcxComboConfig {
   stickyLimit?: number;
   /** Used when the client omits reasoning.effort. null/omitted leaves the target default unchanged. */
   defaultEffort?: OcxComboDefaultEffort | null;
+  /**
+   * Disable image input even when every target supports it.
+   * Omitted / `"auto"` keeps automatic capability derivation (default: enabled when
+   * the target intersection includes image).
+   */
+  imageInput?: "auto" | "disabled";
   /**
    * Optional public model name replacing the default `combo/<id>` slug. Bare names
    * without "/" are allowed (e.g. "deepseek-v4-flash") so the combo can answer to a
@@ -1234,12 +1280,28 @@ export interface ProviderCostOverlay {
   cacheWrite: number;
 }
 
+export interface RequestPacingRule {
+  /** Evenly spread request starts to this many requests per minute. */
+  requestsPerMinute?: number;
+  /** Minimum delay between request starts. The slower configured value wins. */
+  minIntervalMs?: number;
+}
+
+export interface ProviderRequestPacingConfig extends RequestPacingRule {
+  /** False preserves legacy behavior with no client-side waiting. */
+  enabled: boolean;
+  /** Exact upstream model-id overrides; other models inherit the provider rule. */
+  models?: Record<string, RequestPacingRule>;
+}
+
 /**
  * One configured provider entry. `authMode` (default `"key"`) decides whether same-target 429
  * retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
  */
 export interface OcxProviderConfig {
   adapter: string;
+  /** Optional outbound request-start pacing shared by this provider and its model overrides. */
+  requestPacing?: ProviderRequestPacingConfig;
   /** Cursor MCP compatibility bounds; positive integers when configured. */
   mcpMaxTools?: number;
   mcpMaxSchemaBytes?: number;
@@ -1282,8 +1344,10 @@ export interface OcxProviderConfig {
    */
   requiresAdjacentResponsesToolResults?: boolean;
   /**
-   * Whether this provider's Responses route honours the OpenAI `service_tier`
-   * parameter. Tri-state: `true` lets fast mode inject/remove the field (an unset
+   * Provider fallback for the OpenAI `service_tier` parameter. On Responses routes this
+   * is the complete wire opt-in; Chat routes additionally require `chatServiceTier` or an
+   * exact-model true declaration.
+   * Tri-state: `true` lets fast mode inject/remove the field (an unset
    * fast mode preserves a caller-supplied value); `false` strips the field and
    * never injects, because an upstream documented as not supporting the parameter
    * must not receive it; absent (`undefined`) leaves the provider unclassified —
@@ -1291,6 +1355,8 @@ export interface OcxProviderConfig {
    * An explicit config value always wins over the registry default.
    */
   supportsServiceTier?: boolean;
+  /** Exact upstream model ids that override the provider-level service-tier capability. */
+  modelSupportsServiceTier?: Record<string, boolean>;
   /**
    * Responses upstream whose native contract accepts plaintext reasoning replay
    * (DeepSeek documents reasoning items with plaintext content). When set, the
@@ -1468,6 +1534,18 @@ export interface OcxProviderConfig {
    * No effect unless `parallelToolCalls === false`; ignored by non-`openai-chat` adapters.
    */
   pinParallelToolCallsFalse?: boolean;
+  /**
+   * Opt-in: extend the no-tool-call terminal continuation guard to this provider's
+   * `openai-chat` routed turns. The guard (originally Anthropic-only, see
+   * devlog/_fin/260706_previous-response-id-400) issues one bounded internal re-ask when a
+   * model announces work but ends the turn without emitting a tool call. Self-hosted
+   * OpenAI-compatible gateways (GLM/Kimi-family, etc.) hit the same premature-completion
+   * pattern, but the heuristic that decides a "suspicious no-tool stop" was tuned on
+   * Anthropic turns, so it stays OFF by default for the many registry providers that share
+   * the `openai-chat` adapter. Enable only for a provider whose models are known to stop
+   * mid-work; non-`openai-chat` adapters ignore this flag.
+   */
+  terminalContinuationGuard?: boolean;
   /**
    * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
    * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
@@ -1479,8 +1557,9 @@ export interface OcxProviderConfig {
    * OpenAI-specific extension with the same hazard as `promptCacheKey` — strict backends
    * reject unknown fields, and 66 registry providers share the `openai-chat` adapter, so a
    * caller-supplied `service_tier` would otherwise turn working requests into upstream 400s.
-   * `supportsServiceTier` is the Responses-wire flag and does not apply here.
-   * Default off; only enable for providers that document this parameter on the chat wire.
+   * Exact models may opt in through `modelSupportsServiceTier` instead; provider-level
+   * `supportsServiceTier: false` remains a global denial. Default off; only enable for
+   * providers that document this parameter on the chat wire.
    */
   chatServiceTier?: boolean;
   /**