@jiayunxie/aerial 0.1.8 → 0.1.10

package/README.md

@@ -73,18 +73,18 @@ You normally do not need to create, copy, or export an API key yourself.
 
 ## Choosing A Model
 
-The easiest path is to let setup show the compatible models:
+The easiest path is to let setup show the compatible models and ask for reasoning effort:
 
 ```bash
 aerial setup codex
 aerial setup claude
 ```
 
-To pin a model without the prompt:
+To skip the prompts:
 
 ```bash
-aerial setup codex --model <responses-model-id>
-aerial setup claude --model <messages-model-id>
+aerial setup codex --model <responses-model-id> --effort <low|medium|high|xhigh|max>
+aerial setup claude --model <messages-model-id> --effort <low|medium|high|xhigh|max>
 ```
 
 To inspect the full model matrix:

package/docs/usage.md

@@ -71,7 +71,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 prompt, pass `--model <responses-model-id>`.
+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 into the `[profiles.aerial]` block as `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`.
 
 ## 6. Configure Claude Code
 
@@ -85,7 +85,15 @@ If Claude Code was previously pointed at another Anthropic-compatible gateway, s
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
-To skip the prompt, pass `--model <messages-model-id>`.
+To skip the prompts, pass `--model <messages-model-id>` and/or `--effort <low|medium|high|xhigh|max>`. Claude `settings.json` does not store an effort value; instead, `setup claude --effort <value>` updates Aerial-wide `defaultEffort` and the local proxy injects it into outgoing `/v1/messages` payloads. Precedence for the Anthropic effort applied to a Claude Opus 4.7 request, in order:
+
+1. An explicit `output_config.effort` in the request body is preserved verbatim.
+2. A legacy `thinking: { type: "enabled", budget_tokens }` is translated to `thinking: { type: "adaptive" }` with a derived `output_config.effort`.
+3. `thinking: { type: "adaptive" }` without an explicit effort is preserved as-is; Aerial does not inject a default.
+4. Otherwise Aerial injects Aerial `defaultEffort` from `~/.aerial/config.json` as `output_config.effort`.
+5. If no Aerial default is set, Aerial falls back to `medium`.
+
+Non-Opus-4.7 Claude requests are not modified.
 
 ## 7. Verify
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiayunxie/aerial",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Local-only GitHub Copilot proxy for Codex CLI and Claude Code.",
   "type": "module",
   "private": false,

package/src/cli.js

@@ -2,12 +2,14 @@
 import { fileURLToPath } from "node:url";
 import { startDeviceFlow, pollDeviceFlow, readGitHubToken, gitHubTokenSource } from "./auth.js";
 import { ensureApiKey, loadConfig, saveConfig } from "./config.js";
+import { configPath } from "./paths.js";
 import { startServer } from "./server.js";
 import { setupClaude, setupCodex, setupStatus, restoreClient, restoreAllClients } from "./setup.js";
 import { serviceInstall, serviceStart, serviceStop, serviceRestart, serviceUninstall, serviceStatus } from "./service.js";
-import { doctor } from "./doctor.js";
+import { doctor, renderDoctorText } from "./doctor.js";
 import { runProbe, formatProbeReport } from "./probe.js";
 import { chooseSetupModel, formatModelChoices } from "./model-selection.js";
+import { chooseSetupEffort, formatEffortSelection, assertValidEffort } from "./setup-selection.js";
 import { printVersion } from "./version.js";
 import { computeAppStatus } from "./app-status.js";
 
@@ -36,8 +38,8 @@ function printHelp() {
 Usage:
   aerial --version
   aerial login
-  aerial setup codex [--model <id>]
-  aerial setup claude [--model <id>]
+  aerial setup codex [--model <id>] [--effort <low|medium|high|xhigh|max>]
+  aerial setup claude [--model <id>] [--effort <low|medium|high|xhigh|max>]
   aerial service install
   aerial status [--json]
 
@@ -58,8 +60,20 @@ function argValue(args, name) {
   return index >= 0 ? args[index + 1] : undefined;
 }
 
-async function selectSetupModel(target, route, args) {
-  const selected = await chooseSetupModel({ target, route, explicitModel: argValue(args, "--model") });
+function requiredArgValue(args, name) {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`${name} requires a value.`);
+  }
+  return value;
+}
+
+async function selectSetupOptions(target, route, args) {
+  const explicitEffort = requiredArgValue(args, "--effort");
+  if (explicitEffort !== undefined) 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 })) {
       console.log(line);
@@ -67,14 +81,38 @@ async function selectSetupModel(target, route, args) {
   } else {
     console.log(`Selected ${target} model: ${selected.model}`);
   }
-  return selected.model;
+  const effortChoice = await chooseSetupEffort({ target, explicitEffort });
+  console.log(formatEffortSelection({ target, effort: effortChoice.effort, source: effortChoice.source }));
+  return {
+    model: selected.model,
+    effort: effortChoice.effort,
+    modelSource: selected.source,
+    effortSource: effortChoice.source,
+    modelDisplayed: Boolean(selected.displayed),
+    effortDisplayed: Boolean(effortChoice.displayed)
+  };
+}
+
+function printSetupCompletionSummary({ heading, cli, model, effort, proxy, configFile, aerialConfigFile, aerialDefaultEffort, backup, auth, notes = [] }) {
+  console.log(heading);
+  console.log(`  cli: ${cli}`);
+  console.log(`  model: ${model}`);
+  console.log(`  effort: ${effort}`);
+  console.log(`  proxy: ${proxy}`);
+  console.log(`  client config: ${configFile}`);
+  console.log(`  aerial config: ${aerialConfigFile}`);
+  console.log(`  aerial defaultEffort: ${aerialDefaultEffort}`);
+  console.log(`  backup: ${backup || "none"}`);
+  console.log(`  auth: ${auth}`);
+  for (const note of notes) console.log(`  note: ${note}`);
 }
 
 function printSetupSummary(status) {
   console.log("clients:");
   for (const client of Object.values(status.clients)) {
     const model = client.model ? ` model=${client.model}` : "";
-    console.log(`  ${client.target}: ${client.state}${model}`);
+    const effort = ` effort=${client.effort || "missing"}`;
+    console.log(`  ${client.target}: ${client.state}${model}${effort}`);
   }
   console.log(`api key: ${status.auth.api_key.exists ? "present" : "missing"}`);
   const ghSource = status.auth.github_token.source;
@@ -186,21 +224,41 @@ async function main() {
 
   if (command === "setup") {
     if (subcommand === "codex") {
-      const model = await selectSetupModel("Codex", "responses", rest);
-      const result = setupCodex({ model, authCommand: codexAuthCommand() });
-      console.log(`Updated Codex config: ${result.file}`);
-      console.log(`Configured Codex model: ${result.model}`);
-      if (result.backup) console.log(`Backup: ${result.backup}`);
-      console.log("Configured Codex to read the local Aerial key automatically.");
+      const options = await selectSetupOptions("Codex", "responses", rest);
+      const result = setupCodex({ model: options.model, effort: options.effort, authCommand: codexAuthCommand() });
+      const config = loadConfig();
+      printSetupCompletionSummary({
+        heading: "Configured Codex",
+        cli: "Codex",
+        model: result.model,
+        effort: result.effort || "missing",
+        proxy: `http://${config.host}:${config.port}/v1`,
+        configFile: result.file,
+        aerialConfigFile: configPath(),
+        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."]
+      });
       return;
     }
     if (subcommand === "claude") {
-      const model = await selectSetupModel("Claude Code", "messages", rest);
-      const result = setupClaude({ model, apiKeyHelper: claudeApiKeyHelper() });
-      console.log(`Updated Claude settings: ${result.file}`);
-      if (result.model) console.log(`Configured Claude default model: ${result.model}`);
-      console.log("Configured Claude Code to read the local Aerial key automatically.");
-      if (result.backup) console.log(`Backup: ${result.backup}`);
+      const options = await selectSetupOptions("Claude Code", "messages", rest);
+      const result = setupClaude({ model: options.model, effort: options.effort, apiKeyHelper: claudeApiKeyHelper() });
+      const config = loadConfig();
+      printSetupCompletionSummary({
+        heading: "Configured Claude Code",
+        cli: "Claude Code",
+        model: result.model || "preserved",
+        effort: result.effort || config.defaultEffort || "missing",
+        proxy: `http://${config.host}:${config.port}`,
+        configFile: result.file,
+        aerialConfigFile: configPath(),
+        aerialDefaultEffort: config.defaultEffort || "missing",
+        backup: result.backup,
+        auth: "apiKeyHelper local Aerial key",
+        notes: ["effort is applied via Aerial defaultEffort and proxy fallback; Claude settings.json does not store an effort value."]
+      });
       return;
     }
     if (subcommand === "all") {
@@ -222,7 +280,8 @@ async function main() {
       console.log(`GitHub token:    ${ghSourceText}`);
       for (const cs of Object.values(status.clients)) {
         const head = `${cs.target.padEnd(7)} state=${cs.state}`;
-        console.log(`${head}  file=${cs.file}`);
+        const effortText = ` effort=${cs.effort || "missing"}`;
+        console.log(`${head}${effortText}  file=${cs.file}`);
         if (cs.backups.length) console.log(`         backups=${cs.backups.length}`);
         if (cs.error) console.log(`         error=${cs.error}`);
       }
@@ -449,11 +508,10 @@ async function main() {
   }
 
   if (command === "doctor") {
-    const result = doctor();
-    for (const check of result.checks) {
-      console.log(`${check.ok ? "OK" : "FAIL"} ${check.name}: ${check.detail}`);
-    }
-    process.exitCode = result.ok ? 0 : 1;
+    const report = await doctor();
+    if (args.includes("--json")) console.log(JSON.stringify(report, null, 2));
+    else console.log(renderDoctorText(report));
+    process.exitCode = report.ok ? 0 : 1;
     return;
   }
 
@@ -470,9 +528,14 @@ async function main() {
     if (subcommand === "set") {
       const [key, value] = rest;
       if (!key || value === undefined) throw new Error("Usage: aerial config set <key> <value>");
-      if (!["host", "port", "defaultModel", "logLevel", "promptCacheRetention", "promptCacheKey"].includes(key)) throw new Error(`Unsupported config key: ${key}`);
+      if (!["host", "port", "defaultModel", "defaultEffort", "logLevel", "promptCacheRetention", "promptCacheKey"].includes(key)) throw new Error(`Unsupported config key: ${key}`);
       if (key === "promptCacheRetention" && !["in_memory", "24h", "off"].includes(value)) throw new Error("promptCacheRetention must be one of: in_memory, 24h, off");
       if (key === "promptCacheKey" && !value.trim()) throw new Error("promptCacheKey must be auto, off, or a non-empty string");
+      if (key === "defaultEffort") {
+        config.defaultEffort = assertValidEffort(value);
+        saveConfig(config);
+        return;
+      }
       config[key] = key === "port" ? Number(value) : value;
       saveConfig(config);
       return;

package/src/config.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { CONFIG_VERSION, DEFAULT_HOST, DEFAULT_PORT, DEFAULT_VERSIONS } from "./constants.js";
 import { apiKeyPath, configPath, readJsonIfExists, writeJsonPrivate, writePrivateFile } from "./paths.js";
 import { hashApiKey, randomApiKey, verifyApiKey } from "./crypto.js";
+import { DEFAULT_EFFORT, normalizeEffort } from "./setup-selection.js";
 
 export function defaultConfig() {
   return {
@@ -10,6 +11,7 @@ export function defaultConfig() {
     port: DEFAULT_PORT,
     apiKeyHash: undefined,
     defaultModel: undefined,
+    defaultEffort: DEFAULT_EFFORT,
     logLevel: "info",
     promptCacheRetention: "in_memory",
     promptCacheKey: "auto",
@@ -24,7 +26,8 @@ export function loadConfig() {
   const defaults = defaultConfig();
   const promptCacheRetention = envRetention === undefined ? (loaded.promptCacheRetention ?? defaults.promptCacheRetention) : envRetention;
   const promptCacheKey = envCacheKey === undefined ? (loaded.promptCacheKey ?? defaults.promptCacheKey) : envCacheKey;
-  return { ...defaults, ...loaded, promptCacheRetention, promptCacheKey, versions: { ...DEFAULT_VERSIONS, ...(loaded.versions || {}) } };
+  const defaultEffort = normalizeEffort(loaded.defaultEffort) || DEFAULT_EFFORT;
+  return { ...defaults, ...loaded, defaultEffort, promptCacheRetention, promptCacheKey, versions: { ...DEFAULT_VERSIONS, ...(loaded.versions || {}) } };
 }
 
 export function saveConfig(config) {

package/src/copilot.js

@@ -4,6 +4,12 @@ import { loadConfig } from "./config.js";
 import { getCopilotToken } from "./auth.js";
 import { logEvent } from "./log.js";
 import { isResponsesWebSocketOptIn, proxyResponsesWebSocket, shouldUseResponsesWebSocket } from "./responses-websocket.js";
+import {
+  fetchModelsCatalog as fetchModelsCatalogShared,
+  findCompatibleModel as findCompatibleModelShared,
+  canonicalClaudeFamily,
+  tokenFingerprintOf
+} from "./model-catalog.js";
 
 function upstreamHeaders(token, extra = {}) {
   const config = loadConfig();
@@ -174,51 +180,22 @@ function withDefaultAnthropicCache(payload) {
   return next;
 }
 
-function canonicalClaudeOpus47Family(model) {
-  return /^claude-opus-4[.-]7(?:-|$)/.test(model) ? "claude-opus-4.7" : undefined;
-}
-
-function modelHasMessagesRoute(model) {
-  const endpoints = Array.isArray(model?.supported_endpoints) ? model.supported_endpoints : [];
-  const routes = Array.isArray(model?.aerial?.routes) ? model.aerial.routes : [];
-  return endpoints.includes("/v1/messages") || routes.includes("messages");
-}
-
-function supportedReasoningEfforts(model) {
-  const supports = model?.capabilities?.supports;
-  const values = supports?.reasoning_effort ?? supports?.reasoning_efforts;
-  if (Array.isArray(values)) return values.map(String);
-  if (typeof values === "string") return [values];
-  return [];
-}
-
-function modelSupportsAdaptiveThinking(model) {
-  const supports = model?.capabilities?.supports;
-  return supports?.adaptive_thinking === true || supports?.thinking?.adaptive === true;
-}
-
-function findAnthropicEffortModel(modelId, effort, models) {
-  if (!Array.isArray(models)) return undefined;
-  const family = canonicalClaudeOpus47Family(modelId);
-  if (!family) return undefined;
-  const candidates = models.filter((model) => {
-    const id = typeof model?.id === "string" ? model.id : "";
-    return canonicalClaudeOpus47Family(id) === family &&
-      modelHasMessagesRoute(model) &&
-      modelSupportsAdaptiveThinking(model) &&
-      supportedReasoningEfforts(model).includes(effort);
-  });
-  return candidates.find((model) => model.id === modelId) || candidates[0];
-}
-
 function withSupportedAnthropicEffort(payload, models) {
   const effort = payload?.output_config?.effort;
   if (effort === undefined) return payload;
   const model = typeof payload?.model === "string" ? payload.model : "";
-  if (!canonicalClaudeOpus47Family(model)) return payload;
+  const family = canonicalClaudeFamily(model);
+  if (!family) return payload;
   const nextEffort = effort === "max" ? "xhigh" : effort;
   if (!["low", "medium", "high", "xhigh"].includes(nextEffort)) return payload;
-  const routed = findAnthropicEffortModel(model, nextEffort, models);
+  const routed = findCompatibleModelShared({
+    models,
+    family,
+    route: "/v1/messages",
+    adaptiveThinking: true,
+    effort: nextEffort,
+    preferredId: model
+  });
   const nextModel = routed?.id || model;
   if (model === nextModel && effort === nextEffort) return payload;
   logEvent("anthropic_effort_route", { model, effort, routedModel: nextModel, routedEffort: nextEffort });
@@ -258,13 +235,42 @@ function withSupportedAnthropicThinking(payload) {
 function shouldLoadAnthropicCatalog(payload) {
   const effort = payload?.output_config?.effort;
   const model = typeof payload?.model === "string" ? payload.model : "";
-  return effort !== undefined && Boolean(canonicalClaudeOpus47Family(model));
+  return effort !== undefined && Boolean(canonicalClaudeFamily(model));
+}
+
+async function fetchModelsCatalogForCopilot() {
+  const token = await getCopilotToken();
+  return fetchModelsCatalogShared({
+    tokenFingerprint: tokenFingerprintOf(token),
+    fetchImpl: async () => {
+      const response = await fetch(`${COPILOT_API_ORIGIN}/models`, { method: "GET", headers: upstreamHeaders(token) });
+      if (!response.ok) return undefined;
+      const payload = await response.json().catch(() => ({}));
+      return Array.isArray(payload?.data) ? payload.data : undefined;
+    }
+  });
+}
+
+function withDefaultAnthropicEffort(payload) {
+  if (payload?.output_config?.effort !== undefined) return payload;
+  if (payload?.thinking?.type === "adaptive") return payload;
+  const model = typeof payload?.model === "string" ? payload.model : "";
+  if (!canonicalClaudeFamily(model)) return payload;
+  const config = loadConfig();
+  const effort = config.defaultEffort || "medium";
+  const outputConfig = payload?.output_config && typeof payload.output_config === "object" && !Array.isArray(payload.output_config)
+    ? payload.output_config
+    : {};
+  logEvent("anthropic_default_effort", { model, effort });
+  return { ...payload, output_config: { ...outputConfig, effort } };
 }
 
 async function withAnthropicDefaults(payload) {
-  const next = withSupportedAnthropicThinking(withDefaultAnthropicCache(payload));
+  const cached = withDefaultAnthropicCache(payload);
+  const thinkingApplied = withSupportedAnthropicThinking(cached);
+  const next = withDefaultAnthropicEffort(thinkingApplied);
   const models = shouldLoadAnthropicCatalog(next)
-    ? await fetchModelsCatalog().catch(() => undefined)
+    ? await fetchModelsCatalogForCopilot().catch(() => undefined)
     : undefined;
   return withSupportedAnthropicEffort(next, models);
 }
@@ -480,11 +486,7 @@ async function proxyFetch(path, request, { extraHeaders = {}, bodyOverride } = {
 }
 
 async function fetchModelsCatalog() {
-  const token = await getCopilotToken();
-  const response = await fetch(`${COPILOT_API_ORIGIN}/models`, { method: "GET", headers: upstreamHeaders(token) });
-  if (!response.ok) return undefined;
-  const payload = await response.json().catch(() => ({}));
-  return Array.isArray(payload.data) ? payload.data : undefined;
+  return fetchModelsCatalogForCopilot();
 }
 
 function responseModelFromCatalog(modelId, models) {

package/src/doctor.js

@@ -1,15 +1,195 @@
-import fs from "node:fs";
-import { apiKeyPath, configPath, githubTokenPath } from "./paths.js";
-import { loadConfig } from "./config.js";
+import { setupStatus } from "./setup.js";
+import { serviceStatus } from "./service.js";
+import { computeAppStatus } from "./app-status.js";
 
-export function doctor() {
-  const config = loadConfig();
+const REPAIRS = Object.freeze({
+  LOGIN: Object.freeze({ command: "aerial", args: ["login"] }),
+  SETUP_CODEX: Object.freeze({ command: "aerial", args: ["setup", "codex"] }),
+  SERVICE_INSTALL: Object.freeze({ command: "aerial", args: ["service", "install"] }),
+  SERVICE_STATUS_JSON: Object.freeze({ command: "aerial", args: ["service", "status", "--json"] })
+});
+
+function buildAuthChecks(setup) {
+  const checks = [];
+  const apiKey = setup.auth.api_key;
+  if (!apiKey.exists) {
+    checks.push({
+      id: "auth.api_key",
+      ok: false,
+      severity: "fail",
+      message: "Aerial local API key is missing. Run setup for the client you use; this repair shows the Codex path.",
+      repair: REPAIRS.SETUP_CODEX
+    });
+  } else {
+    checks.push({ id: "auth.api_key", ok: true, severity: "info", message: "Aerial local API key is present." });
+  }
+  const gh = setup.auth.github_token;
+  if (gh.source === "missing") {
+    checks.push({
+      id: "auth.github_token",
+      ok: false,
+      severity: "fail",
+      message: "GitHub token is not configured. Aerial cannot reach Copilot until you log in.",
+      repair: REPAIRS.LOGIN
+    });
+  } else if (gh.source === "env") {
+    checks.push({
+      id: "auth.github_token",
+      ok: true,
+      severity: "warn",
+      message: "AERIAL_GITHUB_TOKEN is set in this shell only. The background service does not inherit it; run `aerial login` to persist a service-readable token.",
+      repair: REPAIRS.LOGIN
+    });
+  } else {
+    checks.push({ id: "auth.github_token", ok: true, severity: "info", message: "GitHub token is present in the persisted credential file." });
+  }
+  return checks;
+}
+
+function buildClientChecks(setup) {
+  const checks = [];
+  const codex = setup.clients.codex;
+  const claude = setup.clients.claude;
+  const aerialCodex = codex.state === "aerial";
+  const aerialClaude = claude.state === "aerial";
+  if (!aerialCodex && !aerialClaude) {
+    checks.push({
+      id: "clients.aerial_client",
+      ok: false,
+      severity: "fail",
+      message: "No client is wired to Aerial. Run setup for the client you use; this repair shows the Codex path.",
+      repair: REPAIRS.SETUP_CODEX
+    });
+  } else {
+    const wired = [aerialCodex && "codex", aerialClaude && "claude"].filter(Boolean).join(", ");
+    checks.push({ id: "clients.aerial_client", ok: true, severity: "info", message: `Client wired to Aerial: ${wired}.` });
+  }
+  return checks;
+}
+
+function buildServiceChecks(service) {
+  const checks = [];
+  if (service.supported === false) {
+    checks.push({
+      id: "service.supported",
+      ok: false,
+      severity: "warn",
+      message: `Background service is not supported on ${service.platform}; Aerial must run in the foreground.`
+    });
+    return checks;
+  }
+  const installed = Boolean(service.service?.installed);
+  const loaded = Boolean(service.service?.loaded);
+  const healthy = service.health?.aerial === true;
+  if (healthy && !installed) {
+    checks.push({
+      id: "service.foreground_only",
+      ok: true,
+      severity: "warn",
+      message: "Aerial is running in the foreground but no background service is installed; it will not start on reboot.",
+      repair: REPAIRS.SERVICE_INSTALL
+    });
+  } else if (installed && !healthy) {
+    checks.push({
+      id: "service.health",
+      ok: false,
+      severity: "fail",
+      message: loaded
+        ? "Service manager reports the task running, but Aerial /health is not responding."
+        : "Service is installed but not running.",
+      repair: REPAIRS.SERVICE_STATUS_JSON
+    });
+  } else if (!installed && !healthy) {
+    checks.push({
+      id: "service.health",
+      ok: false,
+      severity: "fail",
+      message: "Aerial is not running and no background service is installed.",
+      repair: REPAIRS.SERVICE_INSTALL
+    });
+  } else {
+    checks.push({ id: "service.health", ok: true, severity: "info", message: "Aerial /health is responding." });
+  }
+  if (service.health?.portConflict) {
+    checks.push({
+      id: "service.port_conflict",
+      ok: false,
+      severity: "fail",
+      message: `Port ${service.config?.port} is held by a non-Aerial process: ${service.health.conflictReason || "unknown"}.`,
+      repair: REPAIRS.SERVICE_STATUS_JSON
+    });
+  }
+  const wrapper = service.service?.wrapper;
+  if (wrapper && wrapper.stale === true) {
+    const reasons = Array.isArray(wrapper.staleReasons) ? wrapper.staleReasons.join(", ") : "unknown";
+    checks.push({
+      id: "service.wrapper_stale",
+      ok: true,
+      severity: "warn",
+      message: `Installed service wrapper is stale (${reasons}); reinstall to regenerate it.`,
+      repair: REPAIRS.SERVICE_INSTALL
+    });
+  }
+  return checks;
+}
+
+function summarize(ok, checks) {
+  const fails = checks.filter((c) => c.severity === "fail").length;
+  const warns = checks.filter((c) => c.severity === "warn").length;
+  if (ok && warns === 0) return "All checks passed.";
+  if (ok && warns > 0) return `Aerial is functional with ${warns} warning(s).`;
+  return `${fails} check(s) failed; ${warns} warning(s).`;
+}
+
+export async function doctor({ run, healthFetch, setup, service } = {}) {
+  const setupOut = setup ?? setupStatus();
+  const serviceOut = service ?? await serviceStatus({ ...(run ? { run } : {}), ...(healthFetch ? { healthFetch } : {}) });
+  const app = computeAppStatus(setupOut, serviceOut);
   const checks = [
-    { name: "config", ok: fs.existsSync(configPath()), detail: configPath() },
-    { name: "api_key", ok: Boolean(config.apiKeyHash), detail: fs.existsSync(apiKeyPath()) ? apiKeyPath() : config.apiKeyHash ? "hash configured" : "run: aerial setup codex or aerial setup claude" },
-    { name: "github_token", ok: fs.existsSync(githubTokenPath()) || Boolean(process.env.AERIAL_GITHUB_TOKEN), detail: fs.existsSync(githubTokenPath()) ? githubTokenPath() : "run: aerial login" },
-    { name: "node", ok: Number(process.versions.node.split(".")[0]) >= 22, detail: process.version },
-    { name: "bind", ok: config.host === "127.0.0.1", detail: `${config.host}:${config.port}` }
+    ...buildAuthChecks(setupOut),
+    ...buildClientChecks(setupOut),
+    ...buildServiceChecks(serviceOut)
+  ];
+  const ok = app.ok && checks.every((c) => c.severity !== "fail");
+  return {
+    schema: "aerial.doctor.v1",
+    ok,
+    summary: summarize(ok, checks),
+    checks,
+    status: {
+      schema: app.schema,
+      ok: app.ok,
+      setup: app.setup,
+      service: app.service
+    }
+  };
+}
+
+export function renderRepairCommand(repair) {
+  if (!repair || typeof repair !== "object") return "";
+  const args = Array.isArray(repair.args) ? repair.args : [];
+  return [repair.command, ...args].join(" ");
+}
+
+export function renderDoctorText(report) {
+  const lines = [];
+  lines.push(`aerial doctor: ${report.summary}`);
+  const groups = [
+    ["fail", "Failures"],
+    ["warn", "Warnings"],
+    ["info", "Info"]
   ];
-  return { ok: checks.every((check) => check.ok), checks };
+  for (const [severity, label] of groups) {
+    const items = report.checks.filter((c) => c.severity === severity);
+    if (items.length === 0) continue;
+    lines.push("");
+    lines.push(`${label}:`);
+    for (const check of items) {
+      const tag = severity.toUpperCase();
+      let line = `  ${tag} ${check.id}: ${check.message}`;
+      if (check.repair) line += ` -> run: ${renderRepairCommand(check.repair)}`;
+      lines.push(line);
+    }
+  }
+  return lines.join("\n");
 }

package/src/model-catalog.js

@@ -0,0 +1,69 @@
+import crypto from "node:crypto";
+
+const TTL_MS = 30000;
+const cache = new Map();
+
+export function tokenFingerprintOf(token) {
+  if (typeof token !== "string" || token.length === 0) return "anonymous";
+  return crypto.createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
+
+export async function fetchModelsCatalog({ fetchImpl, tokenFingerprint } = {}) {
+  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;
+  cache.set(key, { models, expiresAt: now + TTL_MS });
+  return models;
+}
+
+export function clearModelCatalogCacheForTests() {
+  cache.clear();
+}
+
+export function canonicalClaudeFamily(modelId) {
+  if (typeof modelId !== "string") return undefined;
+  if (/^claude-opus-4[.-]7(?:-|$)/.test(modelId)) return "claude-opus-4.7";
+  return undefined;
+}
+
+function modelHasRoute(model, route) {
+  const endpoints = Array.isArray(model?.supported_endpoints) ? model.supported_endpoints : [];
+  const routes = Array.isArray(model?.aerial?.routes) ? model.aerial.routes : [];
+  if (route === "/v1/messages") return endpoints.includes("/v1/messages") || routes.includes("messages");
+  return endpoints.includes(route);
+}
+
+function modelSupportsAdaptiveThinking(model) {
+  const supports = model?.capabilities?.supports;
+  return supports?.adaptive_thinking === true || supports?.thinking?.adaptive === true;
+}
+
+function supportedReasoningEfforts(model) {
+  const supports = model?.capabilities?.supports;
+  const values = supports?.reasoning_effort ?? supports?.reasoning_efforts;
+  if (Array.isArray(values)) return values.map(String);
+  if (typeof values === "string") return [values];
+  return [];
+}
+
+export function findCompatibleModel({ models, family, route, adaptiveThinking, effort, preferredId } = {}) {
+  if (!Array.isArray(models) || !family) return undefined;
+  const candidates = models.filter((model) => {
+    const id = typeof model?.id === "string" ? model.id : "";
+    if (canonicalClaudeFamily(id) !== family) return false;
+    if (route && !modelHasRoute(model, route)) return false;
+    if (adaptiveThinking === true && !modelSupportsAdaptiveThinking(model)) return false;
+    if (effort && !supportedReasoningEfforts(model).includes(effort)) return false;
+    return true;
+  });
+  if (candidates.length === 0) return undefined;
+  if (preferredId) {
+    const preferred = candidates.find((model) => model.id === preferredId);
+    if (preferred) return preferred;
+  }
+  return candidates[0];
+}

package/src/service.js

@@ -358,21 +358,147 @@ async function pollForAerialUp(host, port, healthFetch, deadlineMs = HEALTH_STAR
   return { cls: lastCls || { mode: "absent" }, probe: lastProbe, attempts, elapsedMs: Date.now() - start };
 }
 
-function readWrapperNodePath(wrapperFile) {
-  if (!wrapperFile) return undefined;
+function unescapeShSingleQuoted(line, prefix) {
+  if (!line.startsWith(prefix)) return undefined;
+  const rest = line.slice(prefix.length);
+  if (!rest.startsWith("'")) return undefined;
+  let i = 1;
+  let out = "";
+  while (i < rest.length) {
+    const ch = rest[i];
+    if (ch === "'") {
+      if (rest.slice(i, i + 4) === "'\\''") {
+        out += "'";
+        i += 4;
+        continue;
+      }
+      return out;
+    }
+    out += ch;
+    i += 1;
+  }
+  return undefined;
+}
+
+function unescapePsSingleQuoted(line, prefix) {
+  if (!line.startsWith(prefix)) return undefined;
+  const rest = line.slice(prefix.length);
+  if (!rest.startsWith("'")) return undefined;
+  let i = 1;
+  let out = "";
+  while (i < rest.length) {
+    const ch = rest[i];
+    if (ch === "'") {
+      if (rest[i + 1] === "'") {
+        out += "'";
+        i += 2;
+        continue;
+      }
+      return out;
+    }
+    out += ch;
+    i += 1;
+  }
+  return undefined;
+}
+
+function parseWrapperPaths(wrapperFile) {
+  if (!wrapperFile) return { node: undefined, cli: undefined };
   try {
-    if (!fs.existsSync(wrapperFile)) return undefined;
+    if (!fs.existsSync(wrapperFile)) return { node: undefined, cli: undefined };
     const data = fs.readFileSync(wrapperFile, "utf8");
+    const lines = data.split(/\r?\n/);
     if (wrapperFile.endsWith(".sh")) {
-      const m = data.match(/^NODE_BIN='([^']*)'/m);
-      return m ? m[1] : undefined;
+      let node;
+      let cli;
+      for (const line of lines) {
+        if (node === undefined) {
+          const candidate = unescapeShSingleQuoted(line, "NODE_BIN=");
+          if (candidate !== undefined) node = candidate;
+        }
+        if (cli === undefined) {
+          const candidate = unescapeShSingleQuoted(line, "CLI_ENTRY=");
+          if (candidate !== undefined) cli = candidate;
+        }
+        if (node !== undefined && cli !== undefined) break;
+      }
+      return { node, cli };
     }
     if (wrapperFile.endsWith(".ps1")) {
-      const m = data.match(/^\$node\s*=\s*'([^']*)'/m);
-      return m ? m[1] : undefined;
+      let node;
+      let cli;
+      for (const line of lines) {
+        if (node === undefined) {
+          const m = line.match(/^\$node\s*=\s*(.*)$/);
+          if (m) {
+            const candidate = unescapePsSingleQuoted(m[1].trim(), "");
+            if (candidate !== undefined) node = candidate;
+          }
+        }
+        if (cli === undefined) {
+          const m = line.match(/^\$cli\s*=\s*(.*)$/);
+          if (m) {
+            const candidate = unescapePsSingleQuoted(m[1].trim(), "");
+            if (candidate !== undefined) cli = candidate;
+          }
+        }
+        if (node !== undefined && cli !== undefined) break;
+      }
+      return { node, cli };
     }
   } catch {}
-  return undefined;
+  return { node: undefined, cli: undefined };
+}
+
+function readWrapperNodePath(wrapperFile) {
+  return parseWrapperPaths(wrapperFile).node;
+}
+
+export const STALE_REASONS = Object.freeze({
+  WRAPPER_MISSING: "wrapper_missing",
+  WRAPPER_NODE_MISSING: "wrapper_node_missing",
+  WRAPPER_CLI_MISSING: "wrapper_cli_missing",
+  WRAPPER_LOG_CONFIG_UNPARSEABLE: "wrapper_log_config_unparseable"
+});
+
+function wrapperBlock(state) {
+  if (!state || state.installed !== true) {
+    return { stale: false, staleReasons: [] };
+  }
+  let wrapperPath;
+  if (process.platform === "darwin") wrapperPath = darwinWrapperPath();
+  else if (process.platform === "win32") wrapperPath = winWrapperPath();
+  const wrapperFileExists = wrapperPath ? fs.existsSync(wrapperPath) : false;
+  const staleReasons = [];
+  if (!wrapperFileExists) {
+    return {
+      path: wrapperPath,
+      nodePath: undefined,
+      nodeExists: undefined,
+      cliPath: undefined,
+      cliExists: undefined,
+      logConfigParseable: undefined,
+      stale: true,
+      staleReasons: [STALE_REASONS.WRAPPER_MISSING]
+    };
+  }
+  const { node: nodePath, cli: cliPath } = parseWrapperPaths(wrapperPath);
+  const nodeExists = nodePath ? fs.existsSync(nodePath) : false;
+  const cliExists = cliPath ? fs.existsSync(cliPath) : false;
+  const logConfigParseable = parseWrapperLogValues(wrapperPath) !== null;
+  if (!nodeExists) staleReasons.push(STALE_REASONS.WRAPPER_NODE_MISSING);
+  if (!cliExists) staleReasons.push(STALE_REASONS.WRAPPER_CLI_MISSING);
+  if (!logConfigParseable) staleReasons.push(STALE_REASONS.WRAPPER_LOG_CONFIG_UNPARSEABLE);
+  return {
+    path: wrapperPath,
+    nodePath,
+    nodeExists,
+    cliPath,
+    cliExists,
+    logConfigParseable,
+    stale: staleReasons.length > 0,
+    staleReasons
+  };
 }
 
 function healthFailedDiagnostics({ wrapper, probe, attempts, elapsedMs }) {
@@ -904,7 +1030,7 @@ export async function serviceStatus({ run = defaultRunCommand, healthFetch } = {
       platform: process.platform,
       supported: false,
       config: { host: config.host, port: config.port },
-      service: { installed: false, loaded: false, reason: "unsupported_platform", platform: process.platform },
+      service: { installed: false, loaded: false, reason: "unsupported_platform", platform: process.platform, wrapper: wrapperBlock({ installed: false }) },
       health: { ok: false, error: "unsupported_platform" },
       logs: logsBlock(),
       auth: authBlock(),
@@ -914,6 +1040,7 @@ export async function serviceStatus({ run = defaultRunCommand, healthFetch } = {
   const state = serviceState(ctx);
   const probe = await (healthFetch || defaultHealthFetch)(config.host, config.port);
   const cls = classifyHealth(probe);
+  const wrapper = wrapperBlock(state);
   let supervisor;
   if (cls.mode === "aerial_running") {
     supervisor = state.installed && state.loaded ? "service-managed" : "foreground";
@@ -939,7 +1066,7 @@ export async function serviceStatus({ run = defaultRunCommand, healthFetch } = {
     platform: process.platform,
     supported: true,
     config: { host: config.host, port: config.port },
-    service: { platform: process.platform, ...state },
+    service: { platform: process.platform, ...state, wrapper },
     health,
     logs: logsBlock(),
     auth: authBlock(),
@@ -956,6 +1083,8 @@ export const _internal = {
   aerialLogPath,
   stdioLogPath,
   parseWrapperLogValues,
+  parseWrapperPaths,
+  wrapperBlock,
   buildSchtasksArgs,
   quoteSchtasksTR,
   classifyHealth

package/src/setup-selection.js

@@ -0,0 +1,71 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export const EFFORT_VALUES = Object.freeze(["low", "medium", "high", "xhigh"]);
+export const DEFAULT_EFFORT = "medium";
+
+export function normalizeEffort(value) {
+  if (value === undefined || value === null) return undefined;
+  const trimmed = String(value).trim().toLowerCase();
+  if (!trimmed) return undefined;
+  if (trimmed === "max") return "xhigh";
+  if (EFFORT_VALUES.includes(trimmed)) return trimmed;
+  return undefined;
+}
+
+export function assertValidEffort(raw) {
+  const normalized = normalizeEffort(raw);
+  if (!normalized) {
+    throw new Error(`Invalid --effort ${JSON.stringify(raw)}. Allowed: ${EFFORT_VALUES.join(", ")} (or alias 'max' for xhigh).`);
+  }
+  return normalized;
+}
+
+function parseChoice(value, max, defaultIndex) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) return defaultIndex;
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const n = Number(trimmed);
+  return n >= 1 && n <= max ? n - 1 : undefined;
+}
+
+export async function chooseSetupEffort({
+  target,
+  explicitEffort,
+  prompt,
+  input: inputStream = input,
+  output: outputStream = output
+} = {}) {
+  if (explicitEffort !== undefined) {
+    return { effort: assertValidEffort(explicitEffort), source: "explicit", displayed: false };
+  }
+  const shouldPrompt = prompt === undefined ? Boolean(inputStream.isTTY) : prompt;
+  if (!shouldPrompt) {
+    return { effort: DEFAULT_EFFORT, source: "default_non_tty", displayed: false };
+  }
+  const defaultIndex = EFFORT_VALUES.indexOf(DEFAULT_EFFORT);
+  const rl = createInterface({ input: inputStream, output: outputStream });
+  try {
+    outputStream.write(`Choose ${target} reasoning effort:\n`);
+    for (const [index, value] of EFFORT_VALUES.entries()) {
+      const marker = index === defaultIndex ? "  (default)" : "";
+      outputStream.write(`  ${index + 1}. ${value}${marker}\n`);
+    }
+    while (true) {
+      const answer = await rl.question(`Choose effort [1-${EFFORT_VALUES.length}, default ${defaultIndex + 1} = ${DEFAULT_EFFORT}]: `);
+      const selectedIndex = parseChoice(answer, EFFORT_VALUES.length, defaultIndex);
+      if (selectedIndex !== undefined) {
+        return { effort: EFFORT_VALUES[selectedIndex], source: "prompt", displayed: true };
+      }
+      outputStream.write(`Enter a number from 1 to ${EFFORT_VALUES.length}, or press Enter for ${defaultIndex + 1}.\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export function formatEffortSelection({ target, effort, source }) {
+  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.`;
+}

package/src/setup.js

@@ -2,10 +2,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
-import { ensureApiKey, loadConfig } from "./config.js";
+import { ensureApiKey, loadConfig, saveConfig } from "./config.js";
 import { apiKeyPath, githubTokenPath } from "./paths.js";
 import { gitHubTokenSource } from "./auth.js";
 import { logEvent } from "./log.js";
+import { assertValidEffort, normalizeEffort } from "./setup-selection.js";
 
 const BACKUP_PREFIX = ".aerial-backup-";
 const PRE_RESTORE_PREFIX = ".aerial-pre-restore-";
@@ -75,7 +76,8 @@ function claudeEnvForAerial(currentEnv, config) {
   };
 }
 
-export function setupCodex({ model, authCommand = DEFAULT_CODEX_AUTH } = {}) {
+export function setupCodex({ model, effort, authCommand = DEFAULT_CODEX_AUTH } = {}) {
+  const normalizedEffort = effort === undefined ? undefined : assertValidEffort(effort);
   ensureApiKey();
   const config = loadConfig();
   const selectedModel = model || config.defaultModel;
@@ -89,7 +91,7 @@ export function setupCodex({ model, authCommand = DEFAULT_CODEX_AUTH } = {}) {
   content = setTomlString(content, "model_provider", "aerial");
   content = setTomlString(content, "model", selectedModel);
   content = upsertTomlSection(content, "model_providers.aerial", {
-    name: "Aerial Copilot Local",
+    name: "Aerial",
     base_url: `http://${config.host}:${config.port}/v1`,
     wire_api: "responses"
   });
@@ -99,13 +101,19 @@ export function setupCodex({ model, authCommand = DEFAULT_CODEX_AUTH } = {}) {
     timeout_ms: authCommand.timeout_ms || DEFAULT_CODEX_AUTH.timeout_ms,
     refresh_interval_ms: authCommand.refresh_interval_ms ?? DEFAULT_CODEX_AUTH.refresh_interval_ms
   });
-  content = upsertTomlSection(content, "profiles.aerial", { model_provider: "aerial", model: selectedModel });
+  const profileValues = { model_provider: "aerial", model: selectedModel };
+  if (normalizedEffort) profileValues.model_reasoning_effort = normalizedEffort;
+  content = upsertTomlSection(content, "profiles.aerial", profileValues);
   fs.writeFileSync(file, content, "utf8");
-  logEvent("setup_write", { target: "codex", file, backup, auth: "command" });
-  return { file, backup, model: selectedModel, auth: { type: "command", command: authCommand.command, args: authCommand.args || [] } };
+  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 || [] } };
 }
 
-export function setupClaude({ model, apiKeyHelper = DEFAULT_CLAUDE_API_KEY_HELPER } = {}) {
+export function setupClaude({ model, effort, apiKeyHelper = DEFAULT_CLAUDE_API_KEY_HELPER } = {}) {
+  const normalizedEffort = effort === undefined ? undefined : assertValidEffort(effort);
   ensureApiKey();
   const config = loadConfig();
   const selectedModel = model || config.defaultModel;
@@ -121,8 +129,11 @@ export function setupClaude({ model, apiKeyHelper = DEFAULT_CLAUDE_API_KEY_HELPE
   };
   if (selectedModel) next.model = selectedModel;
   fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, "utf8");
-  logEvent("setup_write", { target: "claude", file, backup, model: selectedModel });
-  return { file, backup, model: selectedModel, apiKeyHelper };
+  if (normalizedEffort && config.defaultEffort !== normalizedEffort) {
+    saveConfig({ ...config, defaultEffort: normalizedEffort });
+  }
+  logEvent("setup_write", { target: "claude", file, backup, model: selectedModel, effort: normalizedEffort });
+  return { file, backup, model: selectedModel, effort: normalizedEffort, apiKeyHelper };
 }
 
 function codexConfigFile() {
@@ -182,25 +193,27 @@ export function codexStatus() {
   const expectedBaseUrl = `http://${config.host}:${config.port}/v1`;
   const file = codexConfigFile();
   const backups = backupPathsFor(file);
-  if (!fs.existsSync(file)) return { target: "codex", state: "missing", file, backups };
+  if (!fs.existsSync(file)) return { target: "codex", state: "missing", file, backups, effort: "missing" };
   let content;
   try {
     content = fs.readFileSync(file, "utf8");
   } catch (err) {
-    return { target: "codex", state: "invalid", file, backups, error: err.message };
+    return { target: "codex", state: "invalid", file, backups, error: err.message, effort: "missing" };
   }
   let doc;
   try {
     doc = parseToml(content);
   } catch (err) {
-    return { target: "codex", state: "invalid", file, backups, error: err.message };
+    return { target: "codex", state: "invalid", file, backups, error: err.message, effort: "missing" };
   }
   const state = codexStateFromDoc(doc, expectedBaseUrl);
   const model = typeof doc?.model === "string" ? doc.model : undefined;
   const baseUrl = typeof doc?.model_providers?.aerial?.base_url === "string"
     ? doc.model_providers.aerial.base_url
     : undefined;
-  return { target: "codex", state, file, backups, model, baseUrl };
+  const profileEffort = doc?.profiles?.aerial?.model_reasoning_effort;
+  const effort = typeof profileEffort === "string" ? (normalizeEffort(profileEffort) || "missing") : "missing";
+  return { target: "codex", state, file, backups, model, baseUrl, effort };
 }
 
 function claudeStateFromDoc(doc, expectedBaseUrl) {
@@ -220,17 +233,18 @@ export function claudeStatus() {
   const expectedBaseUrl = `http://${config.host}:${config.port}`;
   const file = claudeSettingsFile();
   const backups = backupPathsFor(file);
-  if (!fs.existsSync(file)) return { target: "claude", state: "missing", file, backups };
+  const effort = typeof config.defaultEffort === "string" && config.defaultEffort.trim() ? config.defaultEffort.trim() : "missing";
+  if (!fs.existsSync(file)) return { target: "claude", state: "missing", file, backups, effort };
   let doc;
   try {
     doc = JSON.parse(fs.readFileSync(file, "utf8"));
   } catch (err) {
-    return { target: "claude", state: "invalid", file, backups, error: err.message };
+    return { target: "claude", state: "invalid", file, backups, error: err.message, effort };
   }
   const state = claudeStateFromDoc(doc, expectedBaseUrl);
   const model = typeof doc?.model === "string" ? doc.model : undefined;
   const baseUrl = doc?.env?.ANTHROPIC_BASE_URL;
-  return { target: "claude", state, file, backups, model, baseUrl };
+  return { target: "claude", state, file, backups, model, baseUrl, effort };
 }
 
 export function setupStatus() {