@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/service/windows-taskxml.ts

@@ -79,10 +79,11 @@ export function buildWindowsServiceScript(
     windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath(), "path"),
     windowsBatchSet("OCX_SERVICE_LOG", serviceLogPath(), "path"),
     windowsBatchSet("OCX_BUN", bun, "path"),
-    windowsBatchSet("OCX_CLI", cli, "path"),
+    windowsBatchSet("OCX_CLI", cli ?? undefined, "path"),
+    // Standalone executables have no npm package tree; recovery is "replace the executable", so no OCX_PKG_DIR/restore_backup wiring.
     // Package root for the transactional-update restore path (#1942): cli is
     // <pkg>\src\cli\index.ts, so the package dir is three levels up.
-    'for %%I in ("%OCX_CLI%\\..\\..\\..") do set "OCX_PKG_DIR=%%~fI"',
+    cli ? 'for %%I in ("%OCX_CLI%\\..\\..\\..") do set "OCX_PKG_DIR=%%~fI"' : null,
     'if exist "%OCX_API_TOKEN_FILE%" (',
     '  set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"',
     ")",
@@ -101,14 +102,14 @@ export function buildWindowsServiceScript(
     '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] installation is incomplete: bundled Bun is missing; reinstall opencodex, then run ocx service repair',
     "  exit /b 3",
     ")",
-    'if not exist "%OCX_CLI%" (',
-    "  call :restore_backup",
-    ")",
-    'if not exist "%OCX_CLI%" (',
-    '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] installation is incomplete: CLI entry is missing; reinstall opencodex, then run ocx service repair',
-    "  exit /b 3",
-    ")",
-    `"%OCX_BUN%" "%OCX_CLI%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1`,
+    cli ? 'if not exist "%OCX_CLI%" (' : null,
+    cli ? "  call :restore_backup" : null,
+    cli ? ")" : null,
+    cli ? 'if not exist "%OCX_CLI%" (' : null,
+    cli ? '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] installation is incomplete: CLI entry is missing; reinstall opencodex, then run ocx service repair' : null,
+    cli ? "  exit /b 3" : null,
+    cli ? ")" : null,
+    cli ? `"%OCX_BUN%" "%OCX_CLI%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1` : `"%OCX_BUN%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1`,
     "if %ERRORLEVEL% NEQ 0 (",
     '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] child exited with code %ERRORLEVEL%; restarting in 5s',
     // `timeout` needs console stdin and dies with "Input redirection is not supported"

package/src/service.ts

@@ -6,8 +6,12 @@
  * restore it via the command.
  */
 
-export type { ServiceBackend, ServiceInstallState, ServiceStateEvidence } from "./service/state";
-export { SERVICE_MANAGED_ENV, stableLauncherEntry, serviceLogPath, serviceStatePathsForOpenCodexHome, parseServiceInstallState, inspectServiceStateEvidence, currentServiceHomes, serviceHomeMatches, readServiceBackend, serviceReinstallArgs, serviceInstallArgs } from "./service/state";
+export type { ServiceBackend, ServiceInstallState, ServiceStateEvidence, ServiceStateResolution, ServiceOwner, ServiceOwnership, ServiceOwnershipSubject, ServiceOwnershipResolution, ServiceStateSwapDeps, RecordServiceOwnerRequest, RecordServiceOwnerDeps, ReleaseServiceOwnerDeps, RemoveServiceStateDeps } from "./service/state";
+export { SERVICE_MANAGED_ENV, SERVICE_OWNERSHIP_PROTOCOL_VERSION, SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, stableLauncherEntry, serviceLogPath, serviceStatePaths, serviceStatePathsForOpenCodexHome, parseServiceInstallState, parseServiceOwnership, inspectServiceStateEvidence, resolveServiceState, currentServiceHomes, serviceHomeMatches, readServiceBackend, serviceReinstallArgs, serviceInstallArgs, ServiceStateConflictError, ServiceOwnershipSubjectMismatchError, ServiceOwnershipSubjectUnknownError, ServiceTakeoverCompatibilityChangedError, swapServiceInstallState, removeServiceInstallStateRecords, serviceOwnership, resolveServiceOwnership, sameServiceOwnershipSubject, desktopOwnsService, ownershipGrantedTo, recordServiceOwner, releaseServiceOwner } from "./service/state";
+export type { OwnershipMutationLeaseOptions, OwnershipMutationLease } from "./service/ownership-mutation-lease.mjs";
+export { acquireOwnershipMutationLease, withOwnershipMutationLease } from "./service/ownership-mutation-lease.mjs";
+export type { ManagingCliRole, ManagingCliObservation, RegisteredManagingCliInvocation, ServiceTakeoverCompatibilityInput, ServiceTakeoverCompatibility } from "./service/ownership-compatibility";
+export { registeredManagingCliInvocation, assessServiceTakeoverCompatibility, sameServiceTakeoverCompatibility } from "./service/ownership-compatibility";
 export type { ServiceApiTokenOrigin, ProvisionedServiceApiToken } from "./service/guards";
 export { ServiceOwnershipError, isServiceOwnershipError, serviceEnvironmentOwnedHere, assertServiceEnvironmentMatchesInstall, serviceRetryCommand, assertNotAdminToken, assertServiceAuthEnvironment, writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./service/guards";
 export { resolveServiceListenPort, installedServiceListenPort, SERVICE_INSTALL_HEALTH_MS, SERVICE_INSTALL_HEALTH_WINDOWS_MS, serviceInstallHealthMs, confirmServiceServing, reportServiceServing, resolvedProxyEnv } from "./service/health";
@@ -21,7 +25,7 @@ export { buildWindowsServiceScript, buildWindowsSchtasksCreateArgs, buildWindows
 export type { WindowsSchedulerRegistrationStageDeps, FreshWindowsSchedulerRegistrationDeps, RemoveNativeWindowsServiceDeps } from "./service/windows-ops";
 export { windowsListenPort, winswListenPort, writeServiceDefinitionFile, definitionCarriesCredential, stageWindowsSchedulerRegistrationXml, stageElevatedSchedulerRegistration, describeElevatedRegistrationFailure, registerFreshWindowsSchedulerTask, removeNativeWindowsServiceForScheduler, assertWindowsNativeServiceAccountSupported, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, classifyWindowsServiceStop } from "./service/windows-ops";
 export type { ServiceRepairVerb, RepairServiceDeps } from "./service/repair";
-export { repairService } from "./service/repair";
+export { repairService, foreignServiceOwnerRefusal, unknownServiceOwnerRefusal } from "./service/repair";
 export type { ServiceInstallPreparationDeps, FreshWindowsSchedulerInstallDeps, ServiceStopOutcome, ServiceUninstallOutcome } from "./service/orchestration";
 export { proxyStillLiveAfterStop, prepareServiceInstall, installServiceSafely, installFreshWindowsSchedulerSafely, installedServiceRespawnRisk, stopServiceIfInstalledDetailed, setUninstallServiceHooksForTests, uninstallServiceDetailed, uninstallServiceIfInstalled, isServiceInstalled, isServiceViable } from "./service/orchestration";
 export type { ServiceDiagnostic, WindowsTaskDiagnosticIdentityDeps, WindowsServiceDiagnosticInputs, LaunchdServiceDiagnosticInputs } from "./service/diagnostics";

package/src/tray/windows-tray.ps1

@@ -5,7 +5,7 @@ param(
   [Parameter(Mandatory = $true)][string]$OpenCodexHome,
   # Provenance of $BunPath, chosen when the tray entry was built. Optional so an
   # already-installed launcher command from an older version still starts.
-  [ValidateSet("", "override", "bundled", "process")][string]$BunRuntimeSource = "",
+  [ValidateSet("", "override", "bundled", "process", "standalone")][string]$BunRuntimeSource = "",
   [ValidateSet("Run", "Stop")][string]$Mode = "Run",
   [int]$HostPid = 0
 )
@@ -116,6 +116,88 @@ function Start-OcxCommand([string[]]$CommandArgs, [switch]$TrackExit) {
   }
 }
 
+function Parse-StartupHealthText([string]$Text) {
+  foreach ($line in ($Text -split "\r?\n")) {
+    $trimmed = $line.Trim()
+    if (-not $trimmed) { continue }
+    try {
+      $parsed = $trimmed | ConvertFrom-Json
+      if ($parsed.status -in @("native", "protected", "at-risk") -and ($parsed.rebootSafe -is [bool])) {
+        return $parsed
+      }
+    } catch {
+      # A non-JSON line from the CLI (for example a diagnostic banner) is not a
+      # startup-health payload; keep scanning for the actual JSON result.
+      continue
+    }
+  }
+  return $null
+}
+
+function Start-StartupHealthProbe {
+  # Startup safety is machine-local diagnostic state, so the tray asks the CLI to
+  # collect it directly (ocx __startup-health) instead of poking the management API,
+  # which is admin-token gated. The CLI collects the diagnostic straight from the OS,
+  # so it works without the proxy answering and without any credential.
+  #
+  # The child writes into redirected pipes that the tick reads asynchronously: only
+  # the completed Task<string> is ever touched, so a slow or hung diagnostic can never
+  # block the Windows Forms UI thread, and its lifetime is bounded by a kill in the
+  # tick that lets the next refresh replace it instead of stacking another process.
+  try {
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName = $BunPath
+    $psi.Arguments = ((@($CliPath, "__startup-health") | ForEach-Object { ConvertTo-NativeArgument $_ }) -join " ")
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+    $psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
+    $psi.EnvironmentVariables["CODEX_HOME"] = $CodexHome
+    $psi.EnvironmentVariables["OPENCODEX_HOME"] = $OpenCodexHome
+    if ($BunRuntimeSource) {
+      $psi.EnvironmentVariables["OCX_BUN_RUNTIME_SOURCE"] = $BunRuntimeSource
+      $psi.EnvironmentVariables["OCX_BUN_RUNTIME_PATH"] = $BunPath
+    }
+    $process = [System.Diagnostics.Process]::Start($psi)
+    $script:startupProbeProcess = $process
+    # Drain both pipes asynchronously from the start so neither can fill and stall
+    # the child while the tick is only watching the output task's completion.
+    $script:startupProbeOutputTask = $process.StandardOutput.ReadToEndAsync()
+    $script:startupProbeErrorTask = $process.StandardError.ReadToEndAsync()
+    $script:startupProbeStarted = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  } catch {
+    Write-ActionLog "startup-health probe launch failed: $($_.Exception.GetType().Name)"
+    if ($null -ne $script:startupProbeProcess) {
+      # Process.Start succeeded but the async pipe setup failed: Dispose alone
+      # would leave the Bun child running, so terminate it before cleanup.
+      try {
+        $script:startupProbeProcess.Kill()
+        [void]$script:startupProbeProcess.WaitForExit(3000)
+      } catch {
+        Write-ActionLog "startup-health probe launch cleanup failed: $($_.Exception.GetType().Name)"
+      }
+    }
+    Complete-StartupHealthProbe
+  }
+}
+
+function Complete-StartupHealthProbe {
+  $process = $script:startupProbeProcess
+  $script:startupProbeProcess = $null
+  $script:startupProbeOutputTask = $null
+  $script:startupProbeErrorTask = $null
+  if ($null -ne $process) {
+    try {
+      $process.Dispose()
+    } catch {
+      Write-ActionLog "startup-health probe dispose failed: $($_.Exception.GetType().Name)"
+    }
+  }
+}
+
 function Read-ListenTarget {
   foreach ($path in @((Join-Path $OpenCodexHome "runtime-port.json"), (Join-Path $OpenCodexHome "config.json"))) {
     try {
@@ -172,6 +254,15 @@ $exitItem = $menu.Items.Add("Exit Tray")
 $script:online = $false
 $script:port = 10100
 $script:proxyPid = $null
+$script:wasOnline = $false
+$script:startupHealth = $null
+$script:startupHealthCheckedAt = 0L
+$script:startupRefreshMs = 20000L
+$script:startupProbeProcess = $null
+$script:startupProbeOutputTask = $null
+$script:startupProbeErrorTask = $null
+$script:startupProbeStarted = 0L
+$script:startupProbeTimeoutMs = 30000L
 $script:pendingAction = $null
 $script:pendingStarted = 0L
 $script:pendingDeadline = 0L
@@ -228,18 +319,66 @@ function Update-TrayState {
   $pidMatches = $null -eq $target.pid -or [int]$target.pid -eq [int]$health.pid
   $script:online = $null -ne $health -and $health.status -eq "ok" -and $health.service -eq "opencodex" -and [int]$health.port -eq $script:port -and $pidMatches
   $script:proxyPid = if ($script:online) { [int]$health.pid } else { $null }
+  $cameOnline = $script:online -and -not $script:wasOnline
+  $script:wasOnline = $script:online
+  $now = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  if ($null -ne $script:startupProbeProcess) {
+    $probeExited = $false
+    try {
+      $probeExited = $script:startupProbeProcess.HasExited
+    } catch {
+      $probeExited = $true
+    }
+    $probeTimedOut = ($now - $script:startupProbeStarted) -gt $script:startupProbeTimeoutMs
+    if ($probeExited -and $null -ne $script:startupProbeOutputTask -and $script:startupProbeOutputTask.IsCompleted) {
+      $probeStartup = $null
+      try {
+        $probeStartup = Parse-StartupHealthText $script:startupProbeOutputTask.Result
+      } catch {
+        Write-ActionLog "startup-health probe read failed: $($_.Exception.GetType().Name)"
+      }
+      $script:startupHealth = $probeStartup
+      Complete-StartupHealthProbe
+      $script:startupHealthCheckedAt = $now
+    } elseif ($probeTimedOut) {
+      # A hung diagnostic must not survive its refresh slot: terminate it so the
+      # next refresh cannot stack another orphaned Bun process behind it.
+      Write-ActionLog "startup-health probe timed out; terminating it"
+      try {
+        $script:startupProbeProcess.Kill()
+        [void]$script:startupProbeProcess.WaitForExit(3000)
+      } catch {
+        Write-ActionLog "startup-health probe kill failed: $($_.Exception.GetType().Name)"
+      }
+      $script:startupHealth = $null
+      Complete-StartupHealthProbe
+      $script:startupHealthCheckedAt = $now
+    }
+  }
+  $refreshDue =
+    $script:startupHealthCheckedAt -eq 0 -or
+    ($now - $script:startupHealthCheckedAt -gt $script:startupRefreshMs)
+  if ($script:online -and ($cameOnline -or $refreshDue) -and $null -eq $script:startupProbeProcess) {
+    # Record the attempt so launch failures and invalid results remain throttled.
+    $script:startupHealthCheckedAt = $now
+    Start-StartupHealthProbe
+  }
   if ($script:online) {
     $statusItem.Text = "Proxy: Online (port $($script:port))"
     $notify.Text = "opencodex: Online"
     $startItem.Enabled = $false
     $stopItem.Enabled = $true
     $restartItem.Enabled = $true
-    try {
-      $startup = Read-JsonUrl "$origin/api/startup-health"
+    # The management API is admin-token gated, so the tray must not poke
+    # /api/startup-health for the icon. The probe lifecycle maintenance and the
+    # refresh gate above run on every tick (even while offline) so a hung
+    # diagnostic is cleaned up outside the online-only UI branch.
+    $startup = $script:startupHealth
+    if ($null -ne $startup) {
       $label = if ($startup.status -eq "at-risk") { "At risk" } elseif ($startup.status -eq "protected") { "Protected" } else { "Native routing" }
       $safetyItem.Text = "Restart safety: $label"
       $notify.Icon = if ($startup.status -eq "at-risk") { $warningIcon } else { $onlineIcon }
-    } catch {
+    } else {
       $safetyItem.Text = "Restart safety: unavailable"
       $notify.Icon = $warningIcon
     }
@@ -360,6 +499,19 @@ try {
   if ($null -ne $script:pendingProcess) {
     try { $script:pendingProcess.Dispose() } catch { $null = $_ }
   }
+  if ($null -ne $script:startupProbeProcess) {
+    # A probe still running when the tray shuts down would outlive it: Dispose()
+    # releases the handle but does not terminate the child, so kill the active
+    # probe, wait briefly for exit, then release the probe state.
+    try {
+      Write-ActionLog "terminating active startup-health probe on tray shutdown"
+      $script:startupProbeProcess.Kill()
+      [void]$script:startupProbeProcess.WaitForExit(3000)
+    } catch {
+      Write-ActionLog "startup-health probe shutdown kill failed: $($_.Exception.GetType().Name)"
+    }
+    Complete-StartupHealthProbe
+  }
   $notify.Dispose()
   foreach ($icon in $script:ownedIcons) { $icon.Dispose() }
   $menu.Dispose()

package/src/types/config.ts

@@ -137,6 +137,13 @@ export interface OcxClaudeCodeConfig {
   autoContext?: boolean;
   /** Compact-window tokens for auto-context. Default 829_800 (AUTO_COMPACT_WINDOW_DEFAULT). */
   autoCompactWindow?: number;
+  /**
+   * Local CONNECT proxy + TLS listener that intercepts Claude Code's own `api.anthropic.com`
+   * traffic without any `ANTHROPIC_BASE_URL` rewrite (src/claude/intercept). Claude Code reaches
+   * it via `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` in its settings env. Default: enabled on a
+   * hub; the proxy port defaults to the public port + 100.
+   */
+  intercept?: { enabled?: boolean; port?: number };
   /**
    * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
    * 060): Skill-tool results whose skill name matches an entry here are replaced
@@ -166,6 +173,14 @@ export interface OcxClaudeCodeConfig {
   visionSidecar?: { backend?: "openai" | "anthropic" | "routed"; model?: string };
   /** Persisted Claude Desktop four-family routing profile. */
   desktopProfile?: OcxClaudeDesktopProfile;
+  /**
+   * How Claude Desktop reaches opencodex (src/claude/desktop-first-party.ts).
+   * `first-party` (default) leaves the app on its normal claude.ai login and redirects only the
+   * Code tab's Claude Code process through the intercept pair via settings.json env.
+   * `gateway` installs the third-party deployment profile (desktop-3p) for the whole app.
+   * Unset on an install that already applied a gateway profile resolves to `gateway`.
+   */
+  desktopMode?: "first-party" | "gateway";
   /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
   desktopAutoApply?: boolean;
   /**
@@ -253,6 +268,21 @@ export interface OcxApiKeyEntry {
   key: string;
   createdAt: string;
   pendingRotation?: OcxPendingApiKeyRotation;
+  /**
+   * Resolved provider names this key may reach. Absent or empty means every
+   * provider, which is what every existing key has, so adding the field
+   * changes nothing until an operator sets one.
+   */
+  allowedProviders?: string[];
+  /**
+   * Resolved destinations this key may reach, as a bare model id or a
+   * `provider/model` pair. Absent or empty means every model.
+   *
+   * These name destinations, not the selectors a client sends: they are
+   * checked after alias, combo, fallback and compaction resolution, because
+   * that is the only point at which the model about to be billed is known.
+   */
+  allowedModels?: string[];
 }
 
 export interface OcxPendingApiKeyRotation {
@@ -403,6 +433,8 @@ export interface OcxConfig {
   client?: OcxClientConnectionConfig;
   /** Operator-facing redaction policy for management and CLI projections. */
   privacy?: OcxPrivacyConfig;
+  /** Opt-in process-local aggregate request metrics on the authenticated management plane. */
+  metricsExport?: { enabled?: boolean };
   /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
   emptyCompletionRetry?: boolean;
   /** Suppress allowlisted client-facing Codex transport hints; provider enforcement is unchanged. */
@@ -616,6 +648,12 @@ export interface OcxConfig {
   subagentEffortCap?: string;
   /** Global model effort overrides, after provider model/wide pins; none means omission. */
   modelPinnedEfforts?: Record<string, string>;
+  compactionRouting?: {
+    model: string;
+    reasoningEffort?: string;
+    /** Compaction triggers this override covers; omission means `["manual"]`. */
+    triggers?: ("manual" | "auto")[];
+  };
   /**
    * Models hidden from Codex discovery without blocking direct proxy calls. Routed provider ids
    * are excluded from the catalog + /v1/models entirely. Account-qualified native ids hide only
@@ -753,9 +791,9 @@ export interface OcxConfig {
    * 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
-   * changes are not followed.
+   * once at process start, preserving separate HTTP and HTTPS entries; 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 changes are not followed.
    */
   proxy?: string;
   /**
@@ -786,6 +824,13 @@ export interface OcxConfig {
    * See `src/storage/policy.ts`.
    */
   storageCleanupPolicy?: StorageCleanupPolicy;
+  /**
+   * Opt-in ceiling in bytes for `usage.jsonl`. Absent means the ledger grows without limit,
+   * which stays the default: history an operator did not ask to delete is not deleted. Values
+   * below the documented floor are treated as unset rather than enforced, because a ceiling
+   * smaller than a row cannot be met without emptying the file.
+   */
+  usageLedgerMaxBytes?: number;
   /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
   apiKeys?: OcxApiKeyEntry[];
   /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */

package/src/types/provider.ts

@@ -67,6 +67,31 @@ export interface TransientRetryPolicy {
   attempts?: number;
 }
 
+/**
+ * Opt-in replacement of a native Responses send whose upstream connection closed while the
+ * caller had observed nothing (`providers.<name>.retryOnReset`).
+ *
+ * Covers both ambiguous stages the proxy can be in: no response head at all, and a head whose
+ * SSE body carried only control events. Disabled unless the object is present; a bare `{}`
+ * opts in with defaults. Only a request the proxy can judge self-contained is ever replaced;
+ * see `src/server/responses/reset-replay.ts`. The replacement inference may still be billed if
+ * the origin had already started the first one, which is what makes this opt-in rather than
+ * default.
+ */
+export interface ResetReplayPolicy {
+  /** Master switch. Presence of the object also enables the policy (default true). */
+  enabled?: boolean;
+  /**
+   * Replacement sends one LOGICAL request may make, across every leg and every combo child
+   * (1..2, default 1).
+   *
+   * Not a per-leg retry count and not a send budget. A request that resets before the head and
+   * again after it draws on this one number, and each replacement still has to fit inside the
+   * send allowance the leg already had.
+   */
+  replacements?: number;
+}
+
 /**
  * Same-target 429 wait-and-retry policy (`providers.<name>.retryOn429`). When present and not
  * explicitly disabled, the proxy waits and replays the identical request on the same key before
@@ -356,6 +381,22 @@ export interface OcxProviderConfig {
    * `ocxr1` envelopes are still stripped because no upstream can decrypt them.
    */
   preserveResponsesReasoningContent?: boolean;
+  /**
+   * Treat this provider's `modelReasoningEfforts` as authoritative at the wire, not only in the
+   * catalog. Adapters that ship their own per-model effort table (currently `command-code`)
+   * otherwise let that table win for models it knows, so a widened row is advertised in the
+   * picker and then stripped on the way out. Opt-in because presets are SEEDED with the shipped
+   * table: without a declared flag there is no way to tell an operator's row from a copy an
+   * older release persisted. A rung the upstream then refuses is returned as that error rather
+   * than silently retried without the effort, since the operator asked for it.
+   */
+  modelReasoningEffortsAuthoritative?: boolean;
+  /**
+   * Drop replayed Responses `reasoning` items from input history before forwarding.
+   * Some OpenAI-compatible Responses upstreams accept tool-call replay but reject
+   * reasoning output items when they are sent back on a continuation.
+   */
+  dropResponsesReasoningItems?: boolean;
   /**
    * Explicit opt-in for a relay that genuinely fronts OpenAI and can decode native
    * compaction blobs. Absent or false degrades foreign blobs to an opaque note.
@@ -372,6 +413,35 @@ export interface OcxProviderConfig {
    * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
    */
   allowPrivateNetwork?: boolean;
+  /**
+   * Outbound egress for THIS provider, overriding the process-wide `proxy` decision.
+   *
+   * The global `proxy` is one value for every upstream, so it cannot express the split
+   * operators actually need: reach one gateway through a regional proxy while another stays
+   * direct on the local network (#2894). Accepted values:
+   *
+   * - absent — inherit the global proxy decision. Unchanged behaviour.
+   * - `"direct"` or `null` — never use the global proxy for this provider.
+   * - `"http://…"` / `"https://…"` — this provider's own HTTP(S) proxy.
+   * - `"socks5://…"` / `"socks5h://…"` — this provider's own SOCKS5 proxy.
+   *
+   * An empty string is rejected rather than read as DIRECT: a cleared dashboard field must not
+   * silently switch a provider from inheriting the global proxy to refusing it. A malformed
+   * value is rejected at configuration time and again at request time; it never degrades to
+   * either neighbour, because both degradations look like success at the call site.
+   *
+   * Not every transport can carry this. `structure/transports/inventory.md` records which
+   * request paths honour it and which still follow the process-wide value only.
+   */
+  proxy?: string | null;
+  /**
+   * Destinations this provider reaches without a proxy, in `NO_PROXY` syntax.
+   *
+   * Applied to whichever route `proxy` resolved to, so it carves an exemption out of this
+   * provider's own proxy AND out of an inherited global one. That second case is how a
+   * provider exempts a single host without owning a proxy of its own.
+   */
+  noProxy?: string | string[];
   /**
    * Pin the HTTP version used for upstream provider requests. Bun's fetch negotiates
    * HTTP/2 via TLS ALPN by default; some Cloudflare-fronted SSE endpoints hang on
@@ -800,6 +870,19 @@ export interface OcxProviderConfig {
    * incomplete JSON, missing arguments, and empty streams remain truncation errors.
    */
   openaiChatEofTolerance?: boolean;
+  /**
+   * Opt-in: fold a `developer` message into a `system` message instead of forwarding the role.
+   *
+   * `developer` is part of the Chat Completions message role set, so forwarding it is the
+   * default. The role used to be decided by testing the base URL host against
+   * `api.openai.com`, which assumed every OpenAI-compatible gateway rejects a standard role
+   * until proven otherwise — including gateways that proxy OpenAI itself — and quietly gave the
+   * instruction `system` precedence instead (#5213). This flag exists for a destination that
+   * genuinely rejects the role, so the conversion is a recorded decision about that destination
+   * rather than an inference from its hostname. Position is unaffected either way: the message
+   * keeps its slot in the conversation.
+   */
+  foldDeveloperRoleToSystem?: boolean;
   /**
    * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
    * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
@@ -856,6 +939,12 @@ export interface OcxProviderConfig {
    * with defaults. Key-auth `openai-chat` only.
    */
   transientRetryOn5xx?: TransientRetryPolicy;
+  /**
+   * Opt-in replacement of a native Responses send that died while the caller had observed
+   * nothing (`providers.<name>.retryOnReset`). Disabled unless present; a bare `{}` opts in
+   * with defaults. Native Responses sends only, and only for self-contained requests.
+   */
+  retryOnReset?: ResetReplayPolicy;
   /**
    * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
    * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
@@ -901,6 +990,8 @@ export interface OcxProviderConfig {
    * "cloud-code-assist" = Google Antigravity (Cloud Code Assist) OAuth + CCA envelope.
    */
   googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
+  /** Google tool-schema compatibility policy. Omitted preserves compatible report-only behavior. */
+  googleToolSchemaPolicy?: "compatible" | "reject-lossy";
   /** Vertex AI GCP project id (or GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env). */
   project?: string;
   /** Vertex AI location, e.g. "us-central1" or "global" (or GOOGLE_CLOUD_LOCATION env). */

package/src/types/request.ts

@@ -126,6 +126,8 @@ export interface OcxParsedRequest {
    * (see src/responses/compaction.ts).
    */
   _compactionRequest?: boolean;
+  /** Manual compaction moved to another provider: summarize portably even on a canonical ChatGPT target. */
+  _portableCompaction?: boolean;
   /**
    * True when the current request newly introduced a stored compaction summary/marker. Historical
    * markers restored by previous_response_id expansion were already acknowledged and do not reset
@@ -208,8 +210,34 @@ export interface OcxVideoContent {
   videoUrl: string;
 }
 
-/** A user/developer message content part: text or native media. */
-export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent;
+/**
+ * An attached document carried as bytes rather than as a description of itself.
+ *
+ * Both inbound parsers used to reduce an attachment to a title before any adapter ran, so no
+ * adapter could forward one even to a target that has a representation for it, and the caller
+ * could not tell "the model read the document" from "the model was told a document existed"
+ * (#5212).
+ *
+ * `text` is that marker, derived once from what the part knows and kept on the part itself.
+ * Every text-only consumer in the tree reaches a `.text` fallback for a part it does not
+ * recognize, so carrying it here means a wire with no document representation still states the
+ * attachment instead of emitting `undefined` or a mislabelled `[video]`. Only the wires that
+ * have a counterpart read `data`.
+ */
+export interface OcxDocumentContent {
+  type: "document";
+  /** `[document: name]` marker, for every wire with no document representation. */
+  text: string;
+  /** IANA media type of the payload, for example `application/pdf`. */
+  mediaType: string;
+  /** Base64 payload with no `data:` prefix. */
+  data: string;
+  /** The document's own name: an Anthropic document title or a Chat file part's filename. */
+  filename?: string;
+}
+
+/** A user/developer message content part: text, native media, or an attached document. */
+export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent | OcxDocumentContent;
 
 export interface OcxThinkingContent {
   type: "thinking";

package/src/types/tools.ts

@@ -3,6 +3,12 @@ export interface OcxTool {
   description: string;
   parameters: Record<string, unknown>;
   strict?: boolean;
+  /**
+   * Anthropic `tools[*].allowed_callers`: which callers may invoke this tool. Carried rather
+   * than diagnosed, because rebuilding the declaration without it hands the model a tool the
+   * caller had restricted and returns a normal response (#5210).
+   */
+  allowedCallers?: string[];
   /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
   namespace?: string;
   /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
@@ -31,6 +37,19 @@ export function namespacedToolName(namespace: string | undefined, name: string):
   return namespace ? `${namespace}__${name}` : name;
 }
 
+/**
+ * Whether a declaration actually narrows who may call the tool.
+ *
+ * `["direct"]` is the state every unrestricted tool is already in, so treating it as a
+ * restriction would refuse ordinary traffic. Mirrors the `caller_mode` predicate in
+ * src/claude/compatibility.ts, which draws the same line.
+ */
+export function toolRestrictsCallers(tool: Pick<OcxTool, "allowedCallers">): boolean {
+  const callers = tool.allowedCallers;
+  if (callers === undefined) return false;
+  return !(callers.length === 1 && callers[0] === "direct");
+}
+
 /**
  * Dotted alias of a namespaced tool's wire name. Some routed providers (observed: muse-spark
  * via opencode-go) echo a namespaced tool call as "<namespace>.<name>" instead of the flattened
@@ -67,6 +86,20 @@ const CODE_MODE_HELPER_TOOL_NAMES = [
  */
 export const CODE_MODE_EXEC_TOOL_NAME = "exec";
 
+/**
+ * The nested-helper spellings, as a membership view of the same list.
+ *
+ * A code-mode catalog never DECLARES any of them — they exist only as `tools.<helper>(...)` inside
+ * `exec` — so a recorded call under one of these names can only have come from a provider echoing
+ * the helper, which is what makes the set usable as a bounded recovery vocabulary for stored
+ * history (#5095). Kept beside the tuple it is built from so the two can never drift; this is a
+ * different question from `NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES` below, which also covers `exec`
+ * itself because declaring THAT name is what turns normalization on.
+ */
+export const CODE_MODE_HELPER_WIRE_NAMES: ReadonlySet<string> = new Set<string>(
+  CODE_MODE_HELPER_TOOL_NAMES,
+);
+
 /**
  * Spellings that may never be MANUFACTURED as a bare alias for a namespaced tool.
  *

package/src/types.ts

@@ -4,6 +4,7 @@
 export type { OcxTool, OcxToolChoice } from "./types/tools";
 export {
   CODE_MODE_EXEC_TOOL_NAME,
+  CODE_MODE_HELPER_WIRE_NAMES,
   dottedToolName,
   namespacedToolName,
   normalizeDeclaredToolName,
@@ -16,6 +17,7 @@ export {
   isAllowedToolChoice,
   toolChoiceToolPredicate,
   declaresCodeModeExec,
+  toolRestrictsCallers,
   NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES,
 } from "./types/tools";
 
@@ -42,6 +44,7 @@ export type {
   OcxToolResultMessage,
   OcxTextContent,
   OcxImageContent,
+  OcxDocumentContent,
   OcxContentPart,
   OcxThinkingContent,
   OcxToolCall,
@@ -103,6 +106,7 @@ export type {
   ResponsesItemIdRepairConfig,
   RateLimitRetryPolicy,
   TransientRetryPolicy,
+  ResetReplayPolicy,
   ProviderWebSearchBridgeBackend,
   ProviderWebSearchBridgeConfig,
   ProviderCostOverlay,