@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/server/system-env-shell.ts

@@ -1,7 +1,7 @@
 import { accessSync, constants, readFileSync, writeFileSync, unlinkSync, mkdirSync, statSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { getConfigDir } from "../config";
-import { resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
+import { claudeToolSearchEnv, resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
 import { PROXY_MARKER, defaultAuthDetectDeps, detectClaudeAuth, ownAdmissionTokens, type AuthDetectDeps } from "../claude/auth-detect";
 import { resolveClaudeAuthMode } from "../claude/auth-mode";
 import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "../cli/launcher-context";
@@ -128,6 +128,10 @@ export function writeShellEnvFile(
   if (config.claudeCode?.alwaysEnableEffort === true) {
     lines.push(conditional("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1"));
   }
+  // Tool-search deferral (#4838): opt-in, conditional like every other lever so a
+  // value already exported in the user's shell wins.
+  const toolSearch = claudeToolSearchEnv(config.claudeCode?.toolSearch);
+  if (toolSearch !== undefined) lines.push(conditional("ENABLE_TOOL_SEARCH", toolSearch));
   const shellEnvPath = getShellEnvFilePath();
   recordOwnedConfigPath(getConfigDir(), shellEnvPath);
   mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });

package/src/server/system-env.ts

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
-import { resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
+import { claudeToolSearchEnv, resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
 import { PROXY_MARKER } from "../claude/auth-detect";
 import { isProxyAdmissionSecret } from "./auth-cors";
 import type { OcxConfig } from "../types";
@@ -33,6 +33,7 @@ const MANAGED_SYSTEM_ENV_NAMES = new Set<string>([
   "DISABLE_COMPACT",
   "CLAUDE_CODE_AUTO_COMPACT_WINDOW",
   "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT",
+  "ENABLE_TOOL_SEARCH",
 ]);
 
 interface SystemEnvTracking {
@@ -309,6 +310,11 @@ export async function injectSystemEnv(
     if (config.claudeCode?.alwaysEnableEffort === true) {
       injectLever("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
     }
+    // Tool-search deferral (#4838): same opt-in contract as `ocx claude`, so a machine
+    // whose Claude Code is launched from Dock/launchd gets the setting it configured
+    // instead of only terminal sessions. injectLever keeps a user-owned launchd value.
+    const toolSearch = claudeToolSearchEnv(config.claudeCode?.toolSearch);
+    if (toolSearch !== undefined) injectLever("ENABLE_TOOL_SEARCH", toolSearch);
 
     // Shell-hook env file: works for new shells in already-running Terminal.app.
     writeShellEnvFile(port, config, modelEnv, auto, deps);

package/src/server/workflow-refusal.ts

@@ -5,6 +5,10 @@
  * check in `src/server/index.ts` and the pre-dispatch ceiling check in
  * `src/server/responses/core.ts` -- had drifted into saying different things about the same
  * refusal, and because the non-obvious part below has to be stated once and not twice.
+ *
+ * The HTTP admission DECISION lives here too, for the same reason: the lane derivation and the
+ * refusal it produces are two halves of one answer, and keeping them in one file is what stops
+ * a denial from losing the detail that makes it legible on the way out.
  */
 import { formatErrorResponse } from "../bridge";
 import {
@@ -14,9 +18,13 @@ import {
 } from "./request-log";
 import {
   WORKFLOW_LOCAL_REFUSAL_HEADER,
+  admitWorkflowTurn,
   workflowDenialSummary,
   recordWorkflowRefusalEvent,
   type WorkflowDenial,
+  type WorkflowDecision,
+  type WorkflowLane,
+  type WorkflowSpendDenialDetail,
 } from "../lib/workflow-budget";
 
 /**
@@ -54,11 +62,16 @@ export function workflowRefusalResponse(
   logCtx?: RequestLogContext,
   refusalLog?: WorkflowRefusalLog,
   rootId?: string,
+  spend?: WorkflowSpendDenialDetail,
 ): Response {
-  const summary = workflowDenialSummary(reason);
+  // The denial detail, when the caller has it, is what turns "a token ceiling refused this"
+  // into "the account ceiling of 100,000 is spent". It reaches the message, the event ring and
+  // the log row through this one function, so the three cannot drift into saying different
+  // things about the same refusal -- which is what put this module here in the first place.
+  const summary = workflowDenialSummary(reason, spend);
   // Only a caller that decided the refusal ITSELF passes a root id. admitWorkflowTurn already
   // records its own denials, so passing one there would double-count them.
-  if (rootId) recordWorkflowRefusalEvent(rootId, reason);
+  if (rootId) recordWorkflowRefusalEvent(rootId, reason, Date.now(), spend);
   const recordOn = logCtx ?? refusalLog?.logCtx;
   if (recordOn) {
     markLocalRequestLogRefusal(recordOn, summary.code);
@@ -82,3 +95,44 @@ export function workflowRefusalResponse(
   refusal.headers.set("Access-Control-Expose-Headers", WORKFLOW_LOCAL_REFUSAL_HEADER);
   return refusal;
 }
+
+/**
+ * Admit one HTTP turn against its root workflow budget.
+ *
+ * A fan-out shares the conversation it serves. Without a reserve, a worker burst takes every
+ * slot under its own root and the interactive turn that started it waits behind its own
+ * children. A request that names a parent is treated as that fan-out; a top-level request is
+ * the conversation and may use the reserved slots.
+ */
+export function admitHttpWorkflowTurn(headers: Headers): WorkflowDecision | undefined {
+  const rootId = headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const threadId = headers.get("thread-id")?.trim() || undefined;
+  const lane: WorkflowLane = rootId !== undefined && threadId !== undefined && threadId !== rootId
+    ? "worker"
+    : "interactive";
+  return admitWorkflowTurn(rootId, lane, undefined, threadId);
+}
+
+/**
+ * The refusal for a decision {@link admitHttpWorkflowTurn} declined.
+ *
+ * It exists so the denial's own detail survives the trip to the wire. A token-ceiling denial
+ * arrives carrying the scope that refused and the number it refused against, and a caller that
+ * forwarded only `reason` would answer with a 429 that names no ceiling -- which is the
+ * illegible refusal this whole path is built to avoid. No root id is passed on: the admission
+ * check already recorded its own event, and passing one would count the refusal twice.
+ */
+export function workflowDecisionRefusalResponse(
+  decision: Extract<WorkflowDecision, { admitted: false }>,
+  logCtx?: RequestLogContext,
+  refusalLog?: WorkflowRefusalLog,
+): Response {
+  const spend = decision.spendScope !== undefined && decision.spendLimit !== undefined
+    ? {
+      scope: decision.spendScope,
+      limit: decision.spendLimit,
+      ...(decision.spendProjected !== undefined ? { projected: decision.spendProjected } : {}),
+    }
+    : undefined;
+  return workflowRefusalResponse(decision.reason, logCtx, refusalLog, undefined, spend);
+}

package/src/server/ws-bridge.ts

@@ -1,3 +1,4 @@
+import type { NativeResponseControl } from "./responses/native-response-control";
 import type { ServerWebSocket } from "bun";
 import { responsesJsonEventSequence } from "./responses-json-events";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
@@ -17,6 +18,9 @@ type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
 type ResponsesPayloadObserver = (payload: string) => void;
 
 export interface WsData {
+  nativeControl?: NativeResponseControl;
+  /** Content-free per-turn explanation; never a model capability assertion. */
+  nativeSteeringUnavailable?: string;
   headers?: Headers; // base inbound forward headers only; per-turn auth refresh injects current pool tokens
   /**
    * Resolved once at the handshake. Auth is handshake-time only on this path, so
@@ -229,6 +233,7 @@ export async function pumpResponsesSseToWebSocket(
   sseStream: ReadableStream<Uint8Array>,
   options: {
     isCurrent?: () => boolean;
+    untilEof?: boolean;
     onTerminal?: ResponsesTerminalReporter;
     onSsePayload?: ResponsesPayloadObserver;
   } = {},
@@ -251,6 +256,7 @@ export async function pumpResponsesSseToWebSocket(
   const decoder = new TextDecoder();
   const framer = new BoundedSseFrameBuffer();
   let terminalSeen = false;
+  let lastTerminal: ResponsesTerminalStatus | undefined;
 
   const handlePayload = (payload: string): boolean => {
     if (!isCurrent()) return true;
@@ -270,8 +276,10 @@ export async function pumpResponsesSseToWebSocket(
     }
     if (terminalSeen) return true;
     sendTextFrame(ws, payload);
-    const terminalStatus = terminalStatusFromType(type);
+    if (options.untilEof && type === "response.created") lastTerminal = undefined;
+    const terminalStatus = type === "error" && options.untilEof ? "failed" : terminalStatusFromType(type);
     if (terminalStatus) {
+      if (options.untilEof) { lastTerminal = terminalStatus; return false; }
       reportTerminal(terminalStatus);
       terminalSeen = true;
       void reader.cancel().catch(() => {});
@@ -294,6 +302,10 @@ export async function pumpResponsesSseToWebSocket(
       const payload = parseSseBlock(decoder.decode(tail));
       if (payload) handlePayload(payload);
     }
+    if (options.untilEof && lastTerminal && isCurrent() && !clientCancelled) {
+      reportTerminal(lastTerminal);
+      terminalSeen = true;
+    }
     if (!terminalSeen && isCurrent() && !clientCancelled) {
       reportTerminal("incomplete");
       sendProtocolError(ws, 502, "Upstream stream ended before response terminal event");
@@ -368,6 +380,7 @@ export async function sendResponseToWebSocket(
   response: Response,
   isCurrent: () => boolean,
   options: {
+    untilEof?: boolean;
     onTerminal?: ResponsesTerminalReporter;
     onSsePayload?: ResponsesPayloadObserver;
   } = {},
@@ -398,6 +411,7 @@ export async function sendResponseToWebSocket(
   if (contentType.includes("text/event-stream")) {
     await pumpResponsesSseToWebSocket(ws, response.body, {
       isCurrent,
+      untilEof: options.untilEof,
       onTerminal: options.onTerminal,
       onSsePayload: options.onSsePayload,
     });
@@ -420,6 +434,7 @@ export async function sendResponseToWebSocket(
   if (looksLikeSse(prefix)) {
     await pumpResponsesSseToWebSocket(ws, stream, {
       isCurrent,
+      untilEof: options.untilEof,
       onTerminal: options.onTerminal,
       onSsePayload: options.onSsePayload,
     });

package/src/service/cli.ts

@@ -1,6 +1,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { restoreNativeCodexAsync } from "../codex/inject";
+import { describeRetainedCodexProviderTable } from "../codex/inject/restore";
 import { stripGrokConfig } from "../grok/inject";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { statusWinswRaw, type WinswStatus } from "../lib/winsw";
@@ -196,23 +197,28 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     assertServiceAuthEnvironment();
     // A throw used to escape straight to the top level, so the one command that can
     // leave a macOS hub evicted never reached its own serving check (#4236, defect 1f).
-    // Report the failure, then still ask whether anything is listening: on darwin the
-    // rollback inside installLaunchd may have brought the previous job back, and on
-    // Windows the preserve/restart protocol may have done the same. The operator needs
-    // both halves of that answer, and the exit code stays non-zero either way.
+    // Still ask whether anything is listening: on darwin the rollback inside installLaunchd
+    // may have brought the previous job back, and on Windows the preserve/restart protocol
+    // may have done the same. The operator needs both halves of that answer, and the exit
+    // code stays non-zero either way.
+    //
+    // The failure text travels INTO that report rather than being printed here. Printing it
+    // here and then letting the report reach its success line stated both outcomes for one
+    // run — "❌ Service repair failed: ... exit code 199" beside "✅ opencodex service
+    // repaired and serving on port 10100" — and the checkmark was the false half: the
+    // existing registration had been restarted, not repaired (#4914).
     let repairError: unknown;
     try {
       await repairService({ verb });
     } catch (error) {
       repairError = error;
-      console.error(`❌ Service ${verb} failed: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 1;
     }
     // All three platforms: a repair that reports success while nothing serves is the
     // defect class this unit exists to close. Windows bakes its port into the
     // scheduler wrapper or the WinSW XML, both of which installedServiceListenPort()
     // now reads.
-    await reportServiceServing(verb === "restart" ? "restarted" : "repaired");
+    await reportServiceServing(verb === "restart" ? "restarted" : "repaired", {}, repairError);
     if (repairError !== undefined) process.exitCode = 1;
     return;
   }
@@ -264,6 +270,11 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       await maybeShowStarPrompt();
       break;
     case "start":
+      // The installed launcher preserves the recorded CODEX_SQLITE_HOME: a
+      // changed sqlite_home/CODEX_SQLITE_HOME/CODEX_HOME would start the service
+      // on the recorded database while this shell resolves another, splitting
+      // native Codex history between databases. Same guard `stop` already runs.
+      assertServiceEnvironmentMatchesInstall();
       ops.start();
       await reportServiceServing("started");
       break;
@@ -291,7 +302,15 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
           break;
         }
         const restore = await restoreNativeCodexAsync();
-        if (restore.success) console.log("✅ service stopped + native Codex restored.");
+        if (restore.success) {
+          console.log("✅ service stopped + native Codex restored.");
+          // Success is not the whole answer when routing came down but the provider table
+          // stayed. Saying only "restored" here is how a user finds an unexplained
+          // opencodex table in their config weeks later (#4812).
+          if (restore.retainedCodexProviderTable) {
+            console.log(`   ${describeRetainedCodexProviderTable(restore.retainedCodexProviderTable)}`);
+          }
+        }
         else console.error(`⚠️ service stopped, but native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` (or check $CODEX_HOME/config.toml) before using native Codex.`);
         if (!restore.success) process.exitCode = 1;
         // The Grok fence is the other managed config this command owns. Leaving it behind
@@ -339,6 +358,9 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
           console.error(`⚠️ native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` before using native Codex.`);
           process.exitCode = 1;
         }
+        else if (restore.retainedCodexProviderTable) {
+          console.log(`↩️  ${describeRetainedCodexProviderTable(restore.retainedCodexProviderTable)}`);
+        }
         const grok = stripGrokConfig();
         if (grok.changed) console.log(`↩️  ${grok.message}`);
         else if (!grok.ok) {

package/src/service/guards.ts

@@ -10,6 +10,7 @@ import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 import { diagnoseService } from "./diagnostics";
 import type { ServiceDiagnostic } from "./diagnostics";
 import { currentCodexHome, currentOpenCodexHome, normalizePathForCompare, readServiceInstallState } from "./state";
+import { resolveCodexSqliteHome } from "../codex/paths";
 import { win32 } from "node:path";
 
 /**
@@ -61,6 +62,15 @@ export function assertServiceEnvironmentMatchesInstall(): void {
         "Run the service command from the same OpenCodex home so service state and secrets match.",
     );
   }
+  if (state.codexSqliteHome !== undefined) {
+    const actualCodexSqliteHome = resolveCodexSqliteHome({ codexHome: actualCodexHome });
+    if (normalizePathForCompare(state.codexSqliteHome) !== normalizePathForCompare(actualCodexSqliteHome)) {
+      throw new ServiceOwnershipError(
+        `Service was installed with Codex SQLite home=${state.codexSqliteHome}, but the current Codex SQLite home=${actualCodexSqliteHome}. ` +
+          "Run the service command with the same sqlite_home configuration and CODEX_SQLITE_HOME so native Codex history restore updates the correct database.",
+      );
+    }
+  }
 }
 
 function isLoopbackHostname(hostname: string | undefined): boolean {

package/src/service/health.ts

@@ -148,6 +148,19 @@ export async function confirmServiceServing(
   return { ok: false, port };
 }
 
+/**
+ * The operation, as a noun, for a sentence that has to say it did not complete.
+ *
+ * The verb form reads as an accomplished fact ("service repaired"), which is exactly the
+ * claim that must not be made when the operation threw.
+ */
+const SERVICE_OPERATION_NOUN = {
+  installed: "install",
+  started: "start",
+  repaired: "repair",
+  restarted: "restart",
+} as const;
+
 /**
  * Print the outcome of `install` / `start` / `repair` in terms of what the user cares
  * about — is it serving? — instead of whether the manager accepted the registration.
@@ -156,10 +169,18 @@ export async function confirmServiceServing(
  * worker reads the child's exit status, so a registered-but-silent service now makes it
  * fall back to a direct proxy start rather than reporting a successful update over a
  * dead port.
+ *
+ * `precedingFailure` is the error the operation itself threw, when it threw. The serving
+ * probe still runs — a rollback or a preserve/restart protocol may well have left the
+ * previous job answering, and the operator needs that half of the answer (#4236). But the
+ * two halves have to be ONE sentence. Printing the failure separately and then reaching
+ * the success line here reported both outcomes for the same run and credited work that did
+ * not happen: the registration was kept, not repaired (#4914).
  */
 export async function reportServiceServing(
   verb: "installed" | "started" | "repaired" | "restarted",
   deps: Parameters<typeof confirmServiceServing>[0] = {},
+  precedingFailure?: unknown,
 ): Promise<void> {
   const healthBudgetMs = deps.timeoutMs ?? serviceInstallHealthMs();
   // Timed here rather than reported from the budget. confirmServiceServing knocks once
@@ -171,6 +192,28 @@ export async function reportServiceServing(
   const startedAt = now();
   const serving = await confirmServiceServing({ ...deps, timeoutMs: healthBudgetMs });
   const waitedMs = Math.max(0, now() - startedAt);
+  const failureDetail = precedingFailure === undefined
+    ? null
+    : precedingFailure instanceof Error ? precedingFailure.message : String(precedingFailure);
+  const operation = SERVICE_OPERATION_NOUN[verb];
+  if (failureDetail !== null) {
+    // Serving or not, the operation did not complete, so neither branch may print a
+    // checkmark. What differs is whether anything is answering, which is the fact the
+    // operator acts on next.
+    console.error(
+      serving.ok
+        ? `⚠️  Service ${operation} did not complete: ${failureDetail}\n`
+          + `   A proxy is answering on port ${serving.port}, so the existing registration was kept rather than replaced.\n`
+          + `   The ${operation} did not take effect; rerun it once the reported cause is resolved.\n`
+          + `   Log:       ${serviceLogPath()}`
+        : `❌ Service ${operation} failed: ${failureDetail}\n`
+          + `   No proxy answered on port ${serving.port} after ${Math.round(waitedMs / 1000)}s either.\n`
+          + `   Log:       ${serviceLogPath()}\n`
+          + `   Meanwhile: ocx start   (serves in the foreground)`,
+    );
+    process.exitCode = 1;
+    return;
+  }
   if (serving.ok) {
     console.log(`✅ opencodex service ${verb} and serving on port ${serving.port}.`);
     return;

package/src/service/state.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
 import { resolveCodexHomeDir, type CodexHomeDeps } from "../codex/home";
+import { resolveCodexSqliteHome } from "../codex/paths";
 import { durableBunRuntime, type BunRuntimeSource, type DurableBunRuntime } from "../lib/bun-runtime";
 import { WINSW_SHA256, WINSW_VERSION } from "../lib/winsw";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
@@ -218,6 +219,8 @@ export interface ServiceInstallState {
   version: 1 | 2;
   codexHome: string;
   opencodexHome: string;
+  /** Effective Codex SQLite home used by this service's history integration. */
+  codexSqliteHome?: string;
   /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */
   bunPath?: string;
   cliPath?: string;
@@ -241,7 +244,7 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
   if (state.version !== 1 && state.version !== 2) return null;
   if (typeof state.codexHome !== "string" || state.codexHome.length === 0) return null;
   if (typeof state.opencodexHome !== "string" || state.opencodexHome.length === 0) return null;
-  for (const key of ["bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
+  for (const key of ["codexSqliteHome", "bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
     if (state[key] !== undefined && (typeof state[key] !== "string" || state[key].length === 0)) return null;
   }
   if (state.version === 1) {
@@ -254,10 +257,12 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
 
 export function writeServiceInstallState(backend: ServiceBackend = "scheduler", launcherPath?: string | null): void {
   const { bun, cli } = cliEntry();
+  const codexHome = currentCodexHome();
   const state: ServiceInstallState = {
     version: 2,
-    codexHome: currentCodexHome(),
+    codexHome,
     opencodexHome: currentOpenCodexHome(),
+    codexSqliteHome: resolveCodexSqliteHome({ codexHome }),
     bunPath: bun,
     cliPath: cli,
     ...(launcherPath ? { launcherPath } : {}),

package/src/types/accounts.ts

@@ -19,6 +19,10 @@ export interface CodexAccount {
 }
 
 export interface CodexAccountCredentials {
+  /** Read-only Orca auth.json link; Orca exclusively owns OAuth refresh. */
+  sourceAuthPath?: string;
+  /** Bind the link to the originally imported OAuth subject. */
+  sourceSubject?: string;
   accessToken: string;
   refreshToken: string;
   expiresAt: number;

package/src/types/config.ts

@@ -93,6 +93,31 @@ export interface OcxClaudeCodeConfig {
    * forcing effort on every request can leak reasoning params to non-reasoning routes.
    */
   alwaysEnableEffort?: boolean;
+  /**
+   * Opt-in ENABLE_TOOL_SEARCH injection for launched Claude Code sessions (#4838).
+   *
+   * Claude Code turns MCP tool deferral off whenever ANTHROPIC_BASE_URL names a
+   * non-first-party host, so an `ocx claude` session ships every tool schema in
+   * full on every request. Its own diagnostic states the precondition for turning
+   * that back on: "Set ENABLE_TOOL_SEARCH=true (or auto / auto:N) if your proxy
+   * forwards tool_reference blocks."
+   *
+   * Default OFF, because opencodex only forwards them on the NATIVE ANTHROPIC
+   * PASSTHROUGH route, where the body reaches Anthropic untouched. On a translated
+   * route the deferral shape is not representable: compatibility.ts marks
+   * tool_search/tool_reference/deferred_tools unsupported, and toolsToResponses
+   * drops the tool_search server tool while ignoring defer_loading — deferred tools
+   * still carry input_schema on the wire, so the routed provider receives every
+   * schema anyway while Claude Code stops accounting for them and therefore stops
+   * compacting. Under `claudeCode.compatibility: "enforce"` the same request is
+   * rejected with 400 instead.
+   *
+   * `true` injects "true"; a string is passed through verbatim so Claude Code's own
+   * vocabulary (`auto`, `auto:N`, `force`) stays reachable. `false` and absent
+   * inject nothing — they do not force the variable off, because a value the
+   * operator exported themselves always wins.
+   */
+  toolSearch?: boolean | string;
   /**
    * Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
    * Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
@@ -722,9 +747,11 @@ export interface OcxConfig {
     | { enabled: false }
     | { enabled: true; port?: number };
   /**
-   * Outbound HTTP(S) proxy URL for provider requests (e.g. "http://user:pass@proxy:8080", or
-   * "${HTTPS_PROXY}"-style env reference). Mirrored into HTTP_PROXY/HTTPS_PROXY at startup when
-   * those are unset — Bun's fetch honors them for all outbound calls; localhost is excluded.
+   * Outbound proxy URL for provider requests. HTTP(S) example: "http://user:pass@proxy:8080"
+   * or "${HTTPS_PROXY}". SOCKS5 example: "socks5://127.0.0.1:10808" (`ocx start --socks5`).
+   * HTTP URLs are mirrored into HTTP_PROXY/HTTPS_PROXY when unset. SOCKS5 URLs are mirrored
+   * into ALL_PROXY, clear inherited HTTP(S)_PROXY, and use OpenCodex's SOCKS5 transport.
+   * Loopback stays in NO_PROXY.
    * The literal `"auto"` reads the Windows WinINET static proxy (`ProxyEnable`/`ProxyServer`)
    * once at process start; on other platforms, or when the system proxy is off, SOCKS-only,
    * or unreadable, it degrades to direct egress with one log line (#1525). PAC/WPAD and live
@@ -749,6 +776,10 @@ export interface OcxConfig {
   shutdownTimeoutMs?: number;
   /** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt in. */
   websockets?: boolean;
+  /** Experimental single-lane native OpenAI WebSocket steering; default off. */
+  codexNativeSteering?: boolean;
+  /** Experimental, default-off saved function-result injection on native multi-agent WebSockets. */
+  codexNativeInjection?: boolean;
   /**
    * Opt-in auto-cleanup policy for archived Codex sessions (issue #42 Phase 3).
    * Default OFF (`enabled` false / unset). Never enabled implicitly.
@@ -774,6 +805,20 @@ export interface OcxConfig {
    * built-in `openai` provider, so Codex does not select native remote compaction. Default off.
    */
   codexClientCompaction?: boolean;
+  /**
+   * Label Codex shows for the injected `opencodex` provider. Defaults to `OpenCodex Proxy`.
+   *
+   * Presentation only. Routing is keyed on the provider id `opencodex` — the root
+   * `model_provider = "opencodex"` line and the `[model_providers.opencodex]` header — and this
+   * setting never touches either, so renaming the label cannot reroute or orphan a thread whose
+   * row already names that id.
+   *
+   * There is no way to emit an empty label: Codex rejects a provider with no name, so a blank,
+   * over-long, or control-character value falls back to the default rather than writing a config
+   * Codex would refuse to load. "Suppressing" the OpenCodex branding therefore means choosing a
+   * neutral label, not removing the field.
+   */
+  codexProviderDisplayName?: string;
   /**
    * Compatibility mode: temporarily rewrite Codex resume-history metadata while the proxy is active
    * so Codex App can show old OpenAI chats and opencodex-created exec chats under its default
@@ -807,6 +852,16 @@ export interface OcxConfig {
    * absence is the only default state this policy has.
    */
   codexPool?: OcxCodexPoolConfig;
+  /**
+   * Durable token ceilings for the spend-reservation ledger (#4546). Absent means the
+   * historical behaviour exactly: token spend is still accounted and journalled, and nothing
+   * is refused on it.
+   *
+   * Not in `getDefaultConfig()` on purpose, and deliberately shipped with no default figure.
+   * The ledger is on by default, so a default ceiling would start refusing real traffic on
+   * upgrade against a number nobody chose.
+   */
+  spend?: OcxSpendConfig;
   /** Opt-in per-account activation of newly reset Codex quota windows. */
   codexQuotaAutoRefresh?: Record<string, {
     fiveHour?: boolean;
@@ -1381,3 +1436,49 @@ export interface OcxCatalogAutoRefreshConfig {
    */
   intervalMinutes?: number;
 }
+
+/**
+ * One scope's token ceiling.
+ *
+ * An object rather than a bare number because the ledger's scope limit is already a record in
+ * `SpendReservationPolicy`, and a config shape that mirrors the runtime one cannot drift from
+ * it silently. Absent `maxTokens` is the same as an absent scope: observe only.
+ */
+export interface OcxSpendScopeConfig {
+  /**
+   * Tokens the scope may hold at once, counting settled spend, open reservations and
+   * unresolved spend. A reservation is the request's whole input plus its enforceable output
+   * ceiling, so this is compared against a number that assumes every cached prefix misses.
+   *
+   * There is no default. A ceiling is a number only the operator knows -- it depends on the
+   * plan, the account roster and what the install is for -- and the recorded lesson from the
+   * observational phase of #4546 is that guessing one is worse than shipping none.
+   */
+  maxTokens?: number;
+}
+
+/**
+ * Durable spend ceilings (#4546).
+ *
+ * The three scopes intersect: a request is admitted only when its own root workflow, the
+ * identity that would serve it, and the pool it would draw from all have room. That is what
+ * makes the ceiling hold against a caller that mints a fresh root id per request -- the root
+ * is new, the identity and pool are not.
+ *
+ * Every field is optional and an empty section is the same as no section at all.
+ */
+export interface OcxSpendConfig {
+  /** Ceiling for one root workflow -- the user-visible task, including its whole fan-out. */
+  root?: OcxSpendScopeConfig;
+  /** Ceiling for one authenticated identity, across every root it serves. */
+  identity?: OcxSpendScopeConfig;
+  /** Ceiling for one account pool, across every identity in it. */
+  pool?: OcxSpendScopeConfig;
+  /**
+   * Days a dormant scope's accounting is retained. Default 7.
+   *
+   * A scope is dropped only when it is both idle and under its ceiling, so shortening this
+   * cannot hand an exhausted scope a fresh allowance.
+   */
+  retentionDays?: number;
+}

package/src/types/provider.ts

@@ -311,6 +311,19 @@ export interface OcxProviderConfig {
    * preserved after it, and parallel calls stay together with the reasoning turn that produced them.
    */
   requiresAdjacentResponsesToolResults?: boolean;
+  /**
+   * Responses upstream whose parser also rejects a tool call that has no matching output
+   * anywhere in the replayed input, not merely one whose result sits out of order. A call left
+   * dangling by an interrupted stream is answered with an explicit unknown-status placeholder
+   * so the thread can continue.
+   *
+   * Separate from `requiresAdjacentResponsesToolResults` on purpose: adjacency reorders items a
+   * strict parser already accepts in some order, while this synthesizes an item the client never
+   * sent. Kimi accepts a dangling call (#4726), so it must not inherit the synthesis.
+   * `statelessResponses` implies this, because an upstream that stores nothing cannot resolve
+   * the missing half from its own history either.
+   */
+  requiresPairedResponsesToolResults?: boolean;
   /**
    * When enabled, a tool result that is present but empty (no usable text or content
    * part) is rewritten to an explicit annotation before it reaches the upstream wire,
@@ -605,6 +618,8 @@ export interface OcxProviderConfig {
   reasoningEfforts?: string[];
   /** Model-specific Codex-visible reasoning tiers. An empty array means “do not expose effort”. */
   modelReasoningEfforts?: Record<string, string[]>;
+  /** Catalog-only: do not synthesize a missing max rung for matching routed models. */
+  modelSuppressSyntheticMax?: Record<string, boolean>;
   /** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
   modelDefaultReasoningEfforts?: Record<string, string>;
   /** Operator-owned effort override; none omits effort and uses the provider default. */
@@ -664,6 +679,23 @@ export interface OcxProviderConfig {
    * apply_patch passthrough compatibility for OpenAI and unclassified gateways.
    */
   supportsResponsesCustomTools?: boolean;
+  /**
+   * Hosted tool declarations this Responses destination rejects, so they are stripped from
+   * the request instead of being forwarded and 400'd.
+   *
+   * This is how an OpenAI-compatible gateway with a narrower capability set than OpenAI
+   * describes itself. Before it existed, a destination that accepted plain Responses and
+   * `function` tools but rejected hosted `web_search` could only be handled by adding a
+   * hard-coded baseUrl rule to `src/responses/hosted-tool-policy.ts`, so every such gateway
+   * needed a proxy release; a text-only prompt like "Reply exactly with OK" failed before
+   * the model answered because the hosted declaration travelled with it (#5002).
+   *
+   * Values come from `DECLARABLE_HOSTED_TOOL_TYPES`. Spelling variants of one capability
+   * are aliased, so `["web_search"]` also denies `web_search_preview`. Pair this with
+   * `supportsResponsesCustomTools: false` for a gateway that also rejects native custom
+   * tools; the two capabilities are independent and denied independently.
+   */
+  unsupportedHostedTools?: string[];
   /**
    * Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
    * fields or closing events (#893). Disabled by default and applied only to client-facing

package/src/types/request.ts

@@ -68,6 +68,12 @@ export interface OcxParsedRequest {
   _cursorConversationId?: string;
   /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
   _clientThreadId?: string;
+  /**
+   * This request's OWN Codex thread id (`thread-id`), as opposed to `_clientThreadId`, which
+   * carries `x-codex-parent-thread-id` and is therefore shared by every parallel child of one
+   * parent. Only a surface that must distinguish siblings should read it.
+   */
+  _codexOwnThreadId?: string;
   /** True when promptCacheKey identifies a shared cache cohort rather than one conversation. */
   _promptCacheKeyIsSharedCohort?: boolean;
   /** Cursor-only thread owner; may be an opaque process-local Desktop session/thread identity. */
@@ -312,7 +318,7 @@ export interface OcxProviderContinuationState {
 }
 
 export type AdapterEvent =
-  | { type: "heartbeat" }
+  | { type: "heartbeat"; replayUnsafe?: true }
   | { type: "text_delta"; text: string; phase?: OcxMessagePhase }
   | { type: "thinking_delta"; thinking: string }
   // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and