@jiayunxie/aerial 0.2.6 → 0.2.7

package/README.md

@@ -53,6 +53,8 @@ During setup, Aerial reads your Copilot model list, shows the models that work f
 aerial service install
 ```
 
+On Windows, run this command from an Administrator PowerShell or Command Prompt. Aerial registers its background service with Task Scheduler, and Windows requires elevation for that registration step.
+
 4. Check everything from one place:
 
 ```bash
@@ -91,10 +93,12 @@ aerial setup claude
 To skip the prompts:
 
 ```bash
-aerial setup codex --model <responses-model-id> --effort <low|medium|high|xhigh|max>
+aerial setup codex --model <responses-model-id> --effort <minimal|low|medium|high|xhigh|max|ultra>
 aerial setup claude --model <messages-model-id> --effort <low|medium|high|xhigh|max>
 ```
 
+Codex effort is model-aware. Aerial preserves an effort when the selected Copilot model advertises it and otherwise selects the nearest usable effort, preferring the highest level below the request. Codex `minimal` maps to Copilot `none`; `none` is also accepted as an input alias. Claude Code keeps its own effort semantics, where `max` is an alias for `xhigh`.
+
 To inspect the full model matrix:
 
 ```bash
@@ -120,7 +124,7 @@ Advanced override: `AERIAL_UPSTREAM_PROXY` can be set to a bare `http://`, `http
 ```bash
 aerial status           # setup, login, service, and health summary
 aerial proxy status     # upstream proxy mode, egress, and route visibility
-aerial service install  # install and start the background service
+aerial service install  # install and start the background service (Windows: Administrator terminal required)
 aerial doctor           # local diagnostics
 aerial teardown          # restore client configs and uninstall the service
 ```
@@ -141,7 +145,7 @@ Advanced service lifecycle commands are documented in `docs/usage.md`.
 ## Notes
 
 - macOS background service support uses a user LaunchAgent.
-- Windows background service support uses a user Task Scheduler task.
+- Windows background service support uses a user Task Scheduler task. Run `aerial service install` from an Administrator terminal to register it.
 - Linux service management is not built in yet; run `aerial start` or use your own init system.
 - Copilot inference routes are an observed compatibility target and may change upstream.
 

package/docs/usage.md

@@ -67,6 +67,8 @@ aerial service install
 
 Default URL: `http://127.0.0.1:18181`. `aerial service install` is the daily-use path on macOS and Windows because it installs and starts the local background service. Use `aerial start` only when you want a foreground debug process in the current terminal.
 
+On Windows, run `aerial service install` from an Administrator PowerShell or Command Prompt. Aerial registers the background service with Task Scheduler, and Windows requires elevation for that registration step.
+
 ## 5. Configure Codex CLI
 
 ```bash
@@ -91,7 +93,7 @@ The local key is generated and stored by Aerial automatically. Users do not need
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
-To skip the prompts, pass `--model <responses-model-id>` and/or `--effort <low|medium|high|xhigh|max>` (`max` is an alias for `xhigh`). The chosen effort is written as root-level `model_reasoning_effort = "<effort>"` and is also persisted as Aerial-wide `defaultEffort` in `~/.aerial/config.json`. Under non-TTY (CI/pipes) the wizard does not prompt and falls back to the default effort `medium`.
+To skip the prompts, pass `--model <responses-model-id>` and/or `--effort <minimal|low|medium|high|xhigh|max|ultra>`. `none` is accepted as an alias for Codex `minimal`. Aerial resolves the request against the selected model's live Copilot capabilities: supported values are preserved, while unsupported values fall back to the nearest usable level (`ultra` currently becomes `max` on GPT-5.6 models, and `minimal` is sent as Copilot `none`). The resolved Codex value is written as root-level `model_reasoning_effort = "<effort>"`. Codex setup does not change Aerial `defaultEffort`, which remains the Claude proxy fallback. Under non-TTY (CI/pipes) the wizard does not prompt and falls back to `medium` when the selected model supports it.
 
 ## 6. Configure Claude Code
 
@@ -237,7 +239,7 @@ aerial service uninstall
 Aerial ships a thin platform wrapper around the user-mode service primitives provided by the host OS — there is no Aerial-specific daemon. Two platforms are supported:
 
 - macOS: a user-level launchd `LaunchAgent` at `~/Library/LaunchAgents/com.jiayunxie.aerial.plist` invokes a generated POSIX shell wrapper at `<config-dir>/bin/aerial-service.sh`. The plist is regenerated on every `aerial service install` with a `<!-- Generated by aerial; do not edit -->` header, `KeepAlive = { SuccessfulExit = false; Crashed = true }` so the agent only restarts on crash (not on a clean exit), `ThrottleInterval = 10` to cap restart cadence, and no `StandardOutPath`/`StandardErrorPath` keys (the wrapper owns stdio redirection so launchd does not hold a write fd that would race with rotation). The launchctl command path is `gui/<uid>` (per-user agent, no privilege escalation). Start/stop go through `launchctl bootstrap` and `launchctl bootout` against that domain — never `launchctl kill`.
-- Windows: a Task Scheduler task named `AerialLocalProxy`, `/SC ONLOGON /RL LIMITED`, executes a PowerShell wrapper at `<config-dir>\bin\aerial-service.ps1` (default `%APPDATA%\aerial\bin\aerial-service.ps1`). The wrapper is regenerated on every `aerial service install`. The `/TR` argument quotes the wrapper path with normal double quotes so paths that contain spaces or non-ASCII characters work without manual quoting.
+- Windows: a Task Scheduler task named `AerialLocalProxy`, `/SC ONLOGON /RL LIMITED`, executes a PowerShell wrapper at `<config-dir>\bin\aerial-service.ps1` (default `%APPDATA%\aerial\bin\aerial-service.ps1`). The wrapper is regenerated on every `aerial service install`. Run `aerial service install` from an Administrator PowerShell or Command Prompt so Windows allows Aerial to register or refresh the scheduled task. The task itself still runs at user logon with `/RL LIMITED`. The `/TR` argument quotes the wrapper path with normal double quotes so paths that contain spaces or non-ASCII characters work without manual quoting.
 - Linux: not implemented in this release. `aerial service install|start|stop|restart|uninstall` throws an unsupported-platform error and exits 1; `aerial service status --json` still emits a schema-valid document with `"supported": false` and exits 1. Run `aerial start` directly or wrap it in your own init system.
 
 Both wrappers do the same three things before exec-ing the proxy: (1) startup-rotate the captured stdio log (`aerial-stdio.log` → `.1` → `.2` → `.3`) if it has grown beyond the configured cap; (2) export `AERIAL_LOG_FILE=<config-dir>/logs/aerial.log`, plus `AERIAL_LOG_MAX_BYTES` and `AERIAL_LOG_BACKUPS` (default `5242880` / `3`, or whatever value was present in the installer's environment — see below), and — when `AERIAL_CONFIG_DIR` was set at install time — re-export `AERIAL_CONFIG_DIR` so the service sees the same config root as the installer; (3) `exec` `node src/cli/index.js start --host <host> --port <port>` with stdout and stderr appended to `aerial-stdio.log`. By default, the service wrapper uses the same Node.js binary that ran `aerial service install`. Set `AERIAL_SERVICE_NODE` before `aerial service install` to override this explicitly, for example when installing from one Node binary but running the service with another. The structured event log is opt-in via `AERIAL_LOG_FILE`: when this env var is set (always set by the wrapper, never by foreground `aerial start`), structured events go to that file only; when unset, they go to stderr only. There is no double-write.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiayunxie/aerial",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Local GitHub Copilot proxy for Codex CLI and Claude Code with smart HTTP(S)/SOCKS5 upstream proxy support.",
   "type": "module",
   "private": false,
@@ -47,6 +47,6 @@
   "dependencies": {
     "smol-toml": "^1.6.1",
     "socks": "^2.8.9",
-    "undici": "^7.25.0"
+    "undici": "^7.28.0"
   }
 }

package/src/cli/commands/setup.js

@@ -1,13 +1,24 @@
 import { loadConfig } from "../../shared/config.js";
 import { configPath } from "../../shared/paths.js";
 import { restoreAllClients, restoreClient, setupClaude, setupCodex, setupStatus } from "../../setup/index.js";
-import { chooseSetupModel, formatModelChoices, assertValidEffort, chooseSetupEffort, formatEffortSelection } from "../select.js";
+import {
+  assertValidCodexEffort,
+  assertValidEffort,
+  chooseSetupEffort,
+  chooseSetupModel,
+  discoverModelsForRoute,
+  formatEffortSelection,
+  formatModelChoices
+} from "../select.js";
 import { requiredArgValue, claudeApiKeyHelper, codexAuthCommand } from "../helpers.js";
 import { printRestoreResults, printSetupCompletionSummary } from "../output.js";
 
 async function selectSetupOptions(target, route, args) {
   const explicitEffort = requiredArgValue(args, "--effort");
-  if (explicitEffort !== undefined) assertValidEffort(explicitEffort);
+  if (explicitEffort !== undefined) {
+    if (target === "Codex") assertValidCodexEffort(explicitEffort);
+    else assertValidEffort(explicitEffort);
+  }
   const selected = await chooseSetupModel({ target, route, explicitModel: requiredArgValue(args, "--model") });
   if (!selected.displayed) {
     for (const line of formatModelChoices({ target, route, choices: selected.choices, selectedModel: selected.model, source: selected.source, recommended: selected.recommended })) {
@@ -16,8 +27,26 @@ async function selectSetupOptions(target, route, args) {
   } else {
     console.log(`Selected ${target} model: ${selected.model}`);
   }
-  const effortChoice = await chooseSetupEffort({ target, explicitEffort });
-  console.log(formatEffortSelection({ target, effort: effortChoice.effort, source: effortChoice.source }));
+  let selectedModel = selected.choices.find((choice) => choice.id === selected.model);
+  if (!selectedModel && selected.source === "explicit") {
+    try {
+      selectedModel = (await discoverModelsForRoute(route)).find((choice) => choice.id === selected.model);
+    } catch {
+      selectedModel = undefined;
+    }
+  }
+  const effortChoice = await chooseSetupEffort({
+    target,
+    explicitEffort,
+    model: selected.model,
+    supportedEfforts: selectedModel?.supportedEfforts
+  });
+  console.log(formatEffortSelection({
+    target,
+    effort: effortChoice.effort,
+    source: effortChoice.source,
+    supportedEfforts: effortChoice.supportedEfforts
+  }));
   return {
     model: selected.model,
     effort: effortChoice.effort,
@@ -63,7 +92,10 @@ export async function runSetupCli(subcommand, rest) {
       aerialDefaultEffort: config.defaultEffort || "missing",
       backup: result.backup,
       auth: "command-backed local Aerial key",
-      notes: ["restart Codex if it was already running so it reloads the profile."]
+      notes: [
+        "Aerial defaultEffort is the Claude proxy fallback and was left unchanged.",
+        "restart Codex if it was already running so it reloads the profile."
+      ]
     });
     return;
   }

package/src/cli/index.js

@@ -18,7 +18,7 @@ function printHelp() {
 Usage:
   aerial --version
   aerial login
-  aerial setup codex [--model <id>] [--effort <low|medium|high|xhigh|max>]
+  aerial setup codex [--model <id>] [--effort <minimal|low|medium|high|xhigh|max|ultra>]
   aerial setup claude [--model <id>] [--effort <low|medium|high|xhigh|max>]
   aerial service install
   aerial status [--json]

package/src/cli/probe.js

@@ -1,6 +1,7 @@
 import { proxyChatCompletions, proxyMessages, proxyModels, proxyResponses } from "../proxy/index.js";
 import { readJsonSafely } from "../shared/utils.js";
 import { aerialRoutes, usageSummary } from "../proxy/models.js";
+import { supportedReasoningEfforts } from "../proxy/model-catalog.js";
 
 function modelRoutes(model) {
   return aerialRoutes(model);
@@ -59,6 +60,7 @@ export async function runProbe({ live = false } = {}) {
     models: models.map((model) => ({
       id: model.id,
       routes: modelRoutes(model),
+      efforts: supportedReasoningEfforts(model),
       notes: model.aerial?.notes || [],
       supported: Boolean(model.aerial?.supported)
     }))
@@ -117,8 +119,9 @@ export function formatProbeReport(report) {
   lines.push("", "Model matrix:");
   for (const model of report.models) {
     const routes = model.routes.length ? model.routes.join(",") : "-";
+    const efforts = model.efforts.length ? ` efforts=${model.efforts.join(",")}` : "";
     const notes = model.notes.length ? ` notes=${model.notes.join(",")}` : "";
-    lines.push(`- ${model.id}: routes=${routes}${notes}`);
+    lines.push(`- ${model.id}: routes=${routes}${efforts}${notes}`);
   }
   return lines.join("\n");
 }

package/src/cli/select.js

@@ -4,14 +4,34 @@ import { proxyModels } from "../proxy/index.js";
 import { readJsonSafely } from "../shared/utils.js";
 import { modelsForRoute } from "../proxy/models.js";
 import { codexStatus, claudeStatus } from "../setup/clients.js";
-import { DEFAULT_EFFORT, EFFORT_VALUES, assertValidEffort, normalizeEffort } from "../shared/effort.js";
+import {
+  CODEX_EFFORT_VALUES,
+  DEFAULT_EFFORT,
+  EFFORT_VALUES,
+  assertValidCodexEffort,
+  assertValidEffort,
+  normalizeCodexEffort,
+  normalizeEffort,
+  resolveCodexEffort
+} from "../shared/effort.js";
 
 export { modelsForRoute } from "../proxy/models.js";
-export { DEFAULT_EFFORT, EFFORT_VALUES, normalizeEffort, assertValidEffort } from "../shared/effort.js";
+export {
+  CODEX_EFFORT_VALUES,
+  DEFAULT_EFFORT,
+  EFFORT_VALUES,
+  assertValidCodexEffort,
+  assertValidEffort,
+  normalizeCodexEffort,
+  normalizeEffort,
+  resolveCodexEffort
+} from "../shared/effort.js";
 
 const MAX_LISTED_MODELS = 20;
 const GPT_VERSION_RE = /^gpt-(\d+)(?:\.(\d+))?/i;
 const STABLE_GPT_RE = /^gpt-\d+(?:\.\d+)?$/i;
+const CODEX_EFFORT_USAGE = "<minimal|low|medium|high|xhigh|max|ultra>";
+const CLAUDE_EFFORT_USAGE = "<low|medium|high|xhigh|max>";
 
 const CLEAR_LINE = "\x1b[2K";
 const CURSOR_UP = "\x1b[1A";
@@ -219,12 +239,45 @@ function currentModelFor(target) {
 function currentEffortFor(target) {
   try {
     const status = target === "Codex" ? codexStatus() : claudeStatus();
-    return typeof status.effort === "string" ? normalizeEffort(status.effort) : undefined;
+    if (typeof status.effort !== "string") return undefined;
+    return target === "Codex" ? normalizeCodexEffort(status.effort) : normalizeEffort(status.effort);
   } catch {
     return undefined;
   }
 }
 
+export function normalizeEffortCandidates(values) {
+  if (!Array.isArray(values)) return [];
+  const normalized = new Set();
+  for (const value of values) {
+    const effort = normalizeEffort(value);
+    if (effort) normalized.add(effort);
+  }
+  return EFFORT_VALUES.filter((effort) => normalized.has(effort));
+}
+
+export function normalizeCodexEffortCandidates(values) {
+  if (!Array.isArray(values)) return [];
+  const normalized = new Set();
+  for (const value of values) {
+    const effort = normalizeCodexEffort(value);
+    if (effort) normalized.add(effort);
+  }
+  return CODEX_EFFORT_VALUES.filter((effort) => normalized.has(effort));
+}
+
+function effortUsage(target, candidates, restricted) {
+  if (!restricted) return target === "Codex" ? CODEX_EFFORT_USAGE : CLAUDE_EFFORT_USAGE;
+  if (target === "Codex") return `<${candidates.join("|")}>`;
+  const values = [...candidates];
+  if (values.includes("xhigh")) values.push("max");
+  return `<${values.join("|")}>`;
+}
+
+function defaultEffortFor(candidates) {
+  return candidates.includes(DEFAULT_EFFORT) ? DEFAULT_EFFORT : candidates[0];
+}
+
 export async function chooseSetupModel({
   target,
   route,
@@ -302,23 +355,48 @@ export function formatModelChoices({ target, route, choices, selectedModel, sour
 export async function chooseSetupEffort({
   target,
   explicitEffort,
+  model,
+  supportedEfforts,
   prompt,
   input: inputStream = input,
   output: outputStream = output
 } = {}) {
+  const isCodex = target === "Codex";
+  const restrictedEfforts = isCodex
+    ? normalizeCodexEffortCandidates(supportedEfforts)
+    : normalizeEffortCandidates(supportedEfforts);
+  const restricted = restrictedEfforts.length > 0;
+  const globalEfforts = isCodex ? CODEX_EFFORT_VALUES : EFFORT_VALUES;
+  const candidates = restricted ? restrictedEfforts : globalEfforts;
   if (explicitEffort !== undefined) {
-    return { effort: assertValidEffort(explicitEffort), source: "explicit", displayed: false };
+    if (isCodex) {
+      const requested = assertValidCodexEffort(explicitEffort);
+      const resolved = resolveCodexEffort(requested, supportedEfforts);
+      return {
+        effort: resolved.resolvedEffort,
+        source: "explicit",
+        displayed: false,
+        supportedEfforts: restricted ? candidates : undefined
+      };
+    }
+    const effort = assertValidEffort(explicitEffort);
+    if (restricted && !candidates.includes(effort)) {
+      const subject = model ? `${target} model ${model}` : `${target} model`;
+      throw new Error(`Effort ${JSON.stringify(explicitEffort)} is not supported by ${subject}. Allowed: ${effortUsage(target, candidates, true)}.`);
+    }
+    return { effort, source: "explicit", displayed: false, supportedEfforts: restricted ? candidates : undefined };
   }
   const shouldPrompt = prompt === undefined ? Boolean(inputStream.isTTY) : prompt;
   if (!shouldPrompt) {
-    return { effort: DEFAULT_EFFORT, source: "default_non_tty", displayed: false };
+    return { effort: defaultEffortFor(candidates), source: "default_non_tty", displayed: false, supportedEfforts: restricted ? candidates : undefined };
   }
   const current = currentEffortFor(target);
-  const currentIndex = EFFORT_VALUES.indexOf(current);
-  const initialIndex = currentIndex >= 0 ? currentIndex : EFFORT_VALUES.indexOf(DEFAULT_EFFORT);
+  const currentIndex = candidates.indexOf(current);
+  const defaultIndex = candidates.indexOf(DEFAULT_EFFORT);
+  const initialIndex = currentIndex >= 0 ? currentIndex : defaultIndex >= 0 ? defaultIndex : 0;
   const { item, cancelled } = await select({
     title: `Choose ${target} reasoning effort:`,
-    items: EFFORT_VALUES.map((value) => ({ label: value, value })),
+    items: candidates.map((value) => ({ label: value, value })),
     initialIndex,
     getTags: (it) => {
       const tags = [];
@@ -330,11 +408,18 @@ export async function chooseSetupEffort({
     output: outputStream
   });
   if (cancelled) throw new Error(`${target} setup cancelled.`);
-  return { effort: item.value, source: "prompt", displayed: true };
+  const effort = isCodex
+    ? resolveCodexEffort(item.value, supportedEfforts).resolvedEffort
+    : item.value;
+  return { effort, source: "prompt", displayed: true, supportedEfforts: restricted ? candidates : undefined };
 }
 
-export function formatEffortSelection({ target, effort, source }) {
+export function formatEffortSelection({ target, effort, source, supportedEfforts }) {
   if (source === "explicit") return `Selected ${target} effort: ${effort}`;
   if (source === "prompt") return `Selected ${target} effort: ${effort}`;
-  return `No interactive terminal detected; selected ${target} effort: ${effort}. Pass --effort <low|medium|high|xhigh|max> to choose a different effort.`;
+  const restrictedEfforts = target === "Codex"
+    ? normalizeCodexEffortCandidates(supportedEfforts)
+    : normalizeEffortCandidates(supportedEfforts);
+  const restricted = restrictedEfforts.length > 0;
+  return `No interactive terminal detected; selected ${target} effort: ${effort}. Pass --effort ${effortUsage(target, restrictedEfforts, restricted)} to choose a different effort.`;
 }

package/src/proxy/effort-routing.js

@@ -1,44 +1,97 @@
 import { loadConfig } from "../shared/config.js";
 import { logEvent } from "../shared/log.js";
-import { EFFORT_VALUES, normalizeEffort } from "../shared/effort.js";
-import { canonicalClaudeFamily, findCompatibleModel as findCompatibleModelShared } from "./model-catalog.js";
+import { EFFORT_VALUES, normalizeCodexEffort, normalizeEffort, resolveCodexEffort } from "../shared/effort.js";
+import {
+  canonicalClaudeFamily,
+  findCompatibleModel as findCompatibleModelShared,
+  supportedReasoningEfforts
+} from "./model-catalog.js";
 import { withDefaultAnthropicCache, withDefaultPromptCache } from "./cache-policy.js";
 
-function openAIEffortRoute(model, effort) {
+function openAIEffortRoute(model, effort, supportedEfforts) {
   if (effort === undefined) return undefined;
-  const normalized = normalizeEffort(effort);
+  const normalized = normalizeCodexEffort(effort);
   if (!normalized) return undefined;
-  if (/^gpt-5-mini(?:-|$)/.test(model) && normalized === "xhigh") return "high";
-  if (normalized !== String(effort).trim().toLowerCase()) return normalized;
-  return undefined;
+  const requested = String(effort).trim().toLowerCase();
+  const resolved = resolveCodexEffort(normalized, supportedEfforts);
+  if (!resolved) return undefined;
+  const hasSupportedEffortMetadata = Array.isArray(supportedEfforts)
+    && supportedEfforts.some((value) => normalizeCodexEffort(value));
+  if (!hasSupportedEffortMetadata && /^gpt-5-mini(?:-|$)/.test(model) && resolved.wireEffort === "xhigh") {
+    return { effort: "high", reason: "model_compatibility" };
+  }
+  if (resolved.wireEffort === requested) return undefined;
+  return { effort: resolved.wireEffort, reason: resolved.reason };
 }
 
-function withSupportedOpenAIEffort(payload) {
+async function withSupportedOpenAIEffort(payload, loadModels) {
   const model = typeof payload?.model === "string" ? payload.model : "";
   const reasoningEffort = payload?.reasoning && typeof payload.reasoning === "object" ? payload.reasoning.effort : undefined;
-  const nextReasoningEffort = openAIEffortRoute(model, reasoningEffort);
-  const nextFlatEffort = openAIEffortRoute(model, payload?.reasoning_effort);
+  const flatEffort = payload?.reasoning_effort;
+  const hasKnownEffort = normalizeCodexEffort(reasoningEffort) || normalizeCodexEffort(flatEffort);
+  const models = hasKnownEffort && typeof loadModels === "function"
+    ? await loadModels().catch(() => undefined)
+    : undefined;
+  const selectedModel = Array.isArray(models) ? models.find((entry) => entry?.id === model) : undefined;
+  const supportedEfforts = selectedModel ? supportedReasoningEfforts(selectedModel) : undefined;
+  const nextReasoningEffort = openAIEffortRoute(model, reasoningEffort, supportedEfforts);
+  const nextFlatEffort = openAIEffortRoute(model, flatEffort, supportedEfforts);
   if (!nextReasoningEffort && !nextFlatEffort) return payload;
 
   const next = { ...payload };
-  if (nextReasoningEffort) next.reasoning = { ...payload.reasoning, effort: nextReasoningEffort };
-  if (nextFlatEffort) next.reasoning_effort = nextFlatEffort;
+  if (nextReasoningEffort) next.reasoning = { ...payload.reasoning, effort: nextReasoningEffort.effort };
+  if (nextFlatEffort) next.reasoning_effort = nextFlatEffort.effort;
   logEvent("openai_effort_route", {
     model,
-    effort: reasoningEffort ?? payload?.reasoning_effort,
-    routedEffort: nextReasoningEffort ?? nextFlatEffort
+    effort: reasoningEffort ?? flatEffort,
+    routedEffort: nextReasoningEffort?.effort ?? nextFlatEffort?.effort,
+    reason: nextReasoningEffort?.reason ?? nextFlatEffort?.reason
   });
   return next;
 }
 
-export function withOpenAIDefaults(payload) {
-  return withDefaultPromptCache(withSupportedOpenAIEffort(payload));
+export async function withOpenAIDefaults(payload, loadModels) {
+  return withDefaultPromptCache(await withSupportedOpenAIEffort(payload, loadModels));
 }
 
 function objectOrEmpty(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 
+function closestSupportedEffort(model, requestedEffort) {
+  const requestedRank = EFFORT_VALUES.indexOf(requestedEffort);
+  if (requestedRank === -1) return undefined;
+  const supported = supportedReasoningEfforts(model)
+    .map((effort) => normalizeEffort(effort))
+    .filter((effort, index, values) => effort && values.indexOf(effort) === index);
+  if (supported.includes(requestedEffort)) return requestedEffort;
+  if (supported.length === 0) return undefined;
+  const ranked = supported
+    .map((effort) => ({ effort, rank: EFFORT_VALUES.indexOf(effort) }))
+    .filter((entry) => entry.rank !== -1)
+    .sort((a, b) => a.rank - b.rank);
+  const lowerOrEqual = ranked.filter((entry) => entry.rank <= requestedRank);
+  return (lowerOrEqual.at(-1) || ranked[0])?.effort;
+}
+
+function preferredModel(models, modelId) {
+  if (!Array.isArray(models)) return undefined;
+  return models.find((model) => model?.id === modelId);
+}
+
+function fallbackModelForFamily(models, family, preferredId) {
+  const exact = preferredModel(models, preferredId);
+  if (exact) return exact;
+  const base = preferredModel(models, family);
+  if (!base) return undefined;
+  return findCompatibleModelShared({
+    models: [base],
+    family,
+    route: "/v1/messages",
+    adaptiveThinking: true
+  });
+}
+
 function withSupportedAnthropicEffort(payload, models) {
   const effort = payload?.output_config?.effort;
   if (effort === undefined) return payload;
@@ -47,18 +100,33 @@ function withSupportedAnthropicEffort(payload, models) {
   if (!family) return payload;
   const nextEffort = normalizeEffort(effort);
   if (!nextEffort || !EFFORT_VALUES.includes(nextEffort)) return payload;
-  const routed = findCompatibleModelShared({
+  let routedEffort = nextEffort;
+  let routed = findCompatibleModelShared({
     models,
     family,
     route: "/v1/messages",
     adaptiveThinking: true,
-    effort: nextEffort,
+    effort: routedEffort,
     preferredId: model
   });
+  if (!routed) {
+    const fallbackEffort = closestSupportedEffort(fallbackModelForFamily(models, family, model), nextEffort);
+    if (fallbackEffort && fallbackEffort !== nextEffort) {
+      routedEffort = fallbackEffort;
+      routed = findCompatibleModelShared({
+        models,
+        family,
+        route: "/v1/messages",
+        adaptiveThinking: true,
+        effort: routedEffort,
+        preferredId: model
+      });
+    }
+  }
   const nextModel = routed?.id || model;
-  if (model === nextModel && effort === nextEffort) return payload;
-  logEvent("anthropic_effort_route", { model, effort, routedModel: nextModel, routedEffort: nextEffort });
-  return { ...payload, model: nextModel, output_config: { ...payload.output_config, effort: nextEffort } };
+  if (model === nextModel && effort === routedEffort) return payload;
+  logEvent("anthropic_effort_route", { model, effort, routedModel: nextModel, routedEffort });
+  return { ...payload, model: nextModel, output_config: { ...payload.output_config, effort: routedEffort } };
 }
 
 function legacyThinkingEffort(thinking) {

package/src/proxy/index.js

@@ -24,7 +24,7 @@ export async function proxyModels(request) {
 }
 
 export async function proxyResponses(request) {
-  const payload = withOpenAIDefaults(await request.json());
+  const payload = await withOpenAIDefaults(await request.json(), fetchModelsCatalogForCopilot);
   const body = Buffer.from(JSON.stringify(payload));
 
   if (payload?.stream && isResponsesWebSocketOptIn()) {
@@ -67,8 +67,8 @@ export async function proxyMessages(request) {
 }
 
 export async function proxyChatCompletions(request) {
-  const upstreamRequest = await requestWithJsonBody(request, (payload) => {
-    payload = withOpenAIDefaults(payload);
+  const upstreamRequest = await requestWithJsonBody(request, async (payload) => {
+    payload = await withOpenAIDefaults(payload, fetchModelsCatalogForCopilot);
     if (payload.max_tokens !== undefined && payload.max_completion_tokens === undefined) {
       const { max_tokens, ...rest } = payload;
       return { ...rest, max_completion_tokens: max_tokens };

package/src/proxy/model-catalog.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { logEvent } from "../shared/log.js";
 
 const TTL_MS = 30000;
 const cache = new Map();
@@ -8,14 +9,21 @@ export function tokenFingerprintOf(token) {
   return crypto.createHash("sha256").update(token).digest("hex").slice(0, 16);
 }
 
-export async function fetchModelsCatalog({ fetchImpl, tokenFingerprint } = {}) {
+export async function fetchModelsCatalog({ fetchImpl, tokenFingerprint, now = Date.now() } = {}) {
   if (typeof fetchImpl !== "function") return undefined;
   const key = tokenFingerprint || "anonymous";
   const cached = cache.get(key);
-  const now = Date.now();
   if (cached && cached.expiresAt > now) return cached.models;
-  const models = await fetchImpl();
-  if (!Array.isArray(models)) return undefined;
+  let models;
+  try {
+    models = await fetchImpl();
+  } catch {
+    models = undefined;
+  }
+  if (!Array.isArray(models)) {
+    if (cached) logEvent("model_catalog_stale", { reason: "refresh_failed" });
+    return cached?.models;
+  }
   cache.set(key, { models, expiresAt: now + TTL_MS });
   return models;
 }
@@ -26,7 +34,8 @@ export function clearModelCatalogCacheForTests() {
 
 export function canonicalClaudeFamily(modelId) {
   if (typeof modelId !== "string") return undefined;
-  if (/^claude-opus-4[.-]7(?:-|$)/.test(modelId)) return "claude-opus-4.7";
+  const opus = modelId.match(/^claude-opus-4[.-](\d+)(?:-|$)/);
+  if (opus) return `claude-opus-4.${opus[1]}`;
   return undefined;
 }
 
@@ -42,7 +51,7 @@ function modelSupportsAdaptiveThinking(model) {
   return supports?.adaptive_thinking === true || supports?.thinking?.adaptive === true;
 }
 
-function supportedReasoningEfforts(model) {
+export function supportedReasoningEfforts(model) {
   const supports = model?.capabilities?.supports;
   const values = supports?.reasoning_effort ?? supports?.reasoning_efforts;
   if (Array.isArray(values)) return values.map(String);

package/src/proxy/models.js

@@ -1,4 +1,5 @@
 import { copyResponseHeaders } from "./headers.js";
+import { supportedReasoningEfforts } from "./model-catalog.js";
 
 export function aerialSupportForModel(model) {
   const endpoints = Array.isArray(model.supported_endpoints) ? model.supported_endpoints : [];
@@ -35,7 +36,15 @@ export function aerialRoutes(model) {
 export function modelsForRoute(models, route) {
   return models
     .filter((model) => typeof model?.id === "string" && aerialRoutes(model).includes(route))
-    .map((model) => ({ id: model.id, routes: aerialRoutes(model), notes: model.aerial?.notes || [] }));
+    .map((model) => {
+      const supportedEfforts = supportedReasoningEfforts(model);
+      return {
+        id: model.id,
+        routes: aerialRoutes(model),
+        notes: model.aerial?.notes || [],
+        ...(supportedEfforts.length ? { supportedEfforts } : {})
+      };
+    });
 }
 
 export function usageSummary(payload) {

package/src/setup/clients.js

@@ -5,7 +5,7 @@ import { parse as parseToml } from "smol-toml";
 import { ensureApiKey, loadConfig, saveConfig } from "../shared/config.js";
 import { logEvent } from "../shared/log.js";
 import { atomicWriteFile } from "../shared/utils.js";
-import { assertValidEffort, normalizeEffort } from "../shared/effort.js";
+import { assertValidCodexEffort, assertValidEffort, normalizeCodexEffort, normalizeEffort } from "../shared/effort.js";
 import { backupIfExists, backupPathsFor } from "./restore.js";
 import { setTomlRootString, upsertTomlSection, removeTomlSection } from "./toml.js";
 
@@ -38,7 +38,7 @@ function claudeEnvForAerial(currentEnv, config) {
 }
 
 export function setupCodex({ model, effort, authCommand = DEFAULT_CODEX_AUTH } = {}) {
-  const normalizedEffort = effort === undefined ? undefined : assertValidEffort(effort);
+  const normalizedEffort = effort === undefined ? undefined : assertValidCodexEffort(effort);
   ensureApiKey();
   const config = loadConfig();
   const selectedModel = model || config.defaultModel;
@@ -65,9 +65,6 @@ export function setupCodex({ model, effort, authCommand = DEFAULT_CODEX_AUTH } =
   });
   content = removeTomlSection(content, "profiles.aerial");
   atomicWriteFile(file, content);
-  if (normalizedEffort && config.defaultEffort !== normalizedEffort) {
-    saveConfig({ ...config, defaultEffort: normalizedEffort });
-  }
   logEvent("setup_write", { target: "codex", file, backup, auth: "command", effort: normalizedEffort });
   return { file, backup, model: selectedModel, effort: normalizedEffort, auth: { type: "command", command: authCommand.command, args: authCommand.args || [] } };
 }
@@ -146,7 +143,7 @@ export function codexStatus() {
     ? doc.model_providers.aerial.base_url
     : undefined;
   const rootEffort = doc?.model_reasoning_effort;
-  const effort = typeof rootEffort === "string" ? (normalizeEffort(rootEffort) || "missing") : "missing";
+  const effort = typeof rootEffort === "string" ? (normalizeCodexEffort(rootEffort) || "missing") : "missing";
   const legacyProfile = doc?.profiles?.aerial && typeof doc.profiles.aerial === "object";
   const legacyProfileLooksAerial = legacyProfile
     && (doc.profiles.aerial.model_provider === "aerial"

package/src/shared/effort.js

@@ -1,15 +1,29 @@
 export const EFFORT_VALUES = Object.freeze(["low", "medium", "high", "xhigh"]);
+export const CODEX_EFFORT_VALUES = Object.freeze(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
 export const DEFAULT_EFFORT = "medium";
 
-export function normalizeEffort(value) {
+function lower(value) {
   if (value === undefined || value === null) return undefined;
   const trimmed = String(value).trim().toLowerCase();
+  return trimmed || undefined;
+}
+
+export function normalizeEffort(value) {
+  const trimmed = lower(value);
   if (!trimmed) return undefined;
   if (trimmed === "max") return "xhigh";
   if (EFFORT_VALUES.includes(trimmed)) return trimmed;
   return undefined;
 }
 
+export function normalizeCodexEffort(value) {
+  const trimmed = lower(value);
+  if (!trimmed) return undefined;
+  if (trimmed === "none") return "minimal";
+  if (CODEX_EFFORT_VALUES.includes(trimmed)) return trimmed;
+  return undefined;
+}
+
 export function assertValidEffort(raw) {
   const normalized = normalizeEffort(raw);
   if (!normalized) {
@@ -17,3 +31,58 @@ export function assertValidEffort(raw) {
   }
   return normalized;
 }
+
+export function assertValidCodexEffort(raw) {
+  const normalized = normalizeCodexEffort(raw);
+  if (!normalized) {
+    throw new Error(`Invalid --effort ${JSON.stringify(raw)} for Codex. Allowed: ${CODEX_EFFORT_VALUES.join(", ")} (or alias 'none' for minimal).`);
+  }
+  return normalized;
+}
+
+function codexCatalogEfforts(values) {
+  if (!Array.isArray(values)) return [];
+  const seen = new Set();
+  const efforts = [];
+  for (const value of values) {
+    const wireEffort = lower(value);
+    const resolvedEffort = normalizeCodexEffort(wireEffort);
+    if (!resolvedEffort || seen.has(resolvedEffort)) continue;
+    seen.add(resolvedEffort);
+    efforts.push({ resolvedEffort, wireEffort, rank: CODEX_EFFORT_VALUES.indexOf(resolvedEffort) });
+  }
+  return efforts.sort((a, b) => a.rank - b.rank);
+}
+
+export function resolveCodexEffort(requested, supportedEfforts) {
+  const requestedEffort = normalizeCodexEffort(requested);
+  if (!requestedEffort) return undefined;
+  const requestedRank = CODEX_EFFORT_VALUES.indexOf(requestedEffort);
+  const supported = codexCatalogEfforts(supportedEfforts);
+
+  if (supported.length) {
+    const exact = supported.find((entry) => entry.resolvedEffort === requestedEffort);
+    const lowerOrEqual = supported.filter((entry) => entry.rank <= requestedRank);
+    const selected = exact || lowerOrEqual.at(-1) || supported[0];
+    let reason = "exact";
+    if (selected.resolvedEffort !== requestedEffort) {
+      reason = selected.rank < requestedRank ? "downgraded" : "nearest_supported";
+    } else if (selected.wireEffort !== requestedEffort) {
+      reason = "alias";
+    }
+    return {
+      requestedEffort,
+      resolvedEffort: selected.resolvedEffort,
+      wireEffort: selected.wireEffort,
+      reason
+    };
+  }
+
+  if (requestedEffort === "minimal") {
+    return { requestedEffort, resolvedEffort: "minimal", wireEffort: "none", reason: "alias" };
+  }
+  if (requestedEffort === "ultra") {
+    return { requestedEffort, resolvedEffort: "max", wireEffort: "max", reason: "fallback" };
+  }
+  return { requestedEffort, resolvedEffort: requestedEffort, wireEffort: requestedEffort, reason: "exact" };
+}