nemoris 0.1.0 → 0.1.2

package/src/onboarding/phases/auth.js

@@ -1,589 +1,576 @@
-/**
- * Auth phase — orchestrates key detection, validation, .env writing,
- * and provider/router TOML generation.
- *
- * Phase 3 of the onboarding wizard. Zero LLM tokens consumed; does network
- * probes for health checks only.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { providerTemplate, routerTemplate } from "../templates.js";
-import {
-  detectExistingKeys,
-  validateApiKey,
-  validateApiKeyFormat,
-  writeEnvFile,
-  resolveProviders
-} from "../auth/api-key.js";
-import { detectOllama } from "../auth/ollama-detect.js";
-import {
-  initiateOpenAICodexOAuthFlow,
-  inspectOpenAICodexProfile,
-  OPENAI_CODEX_DEFAULT_PROFILE_ID,
-  resolveOpenAICodexAccess,
-} from "../../auth/openai-codex-oauth.js";
-import { getAuthProfile, resolveAuthProfilesPath } from "../../auth/auth-profiles.js";
-import { buildModelSelectionOptions, fetchOpenAIModels } from "../model-catalog.js";
-
-const PROVIDER_CONFIGS = {
-  anthropic: {
-    providerId: "anthropic",
-    adapter: "anthropic",
-    authEnv: "NEMORIS_ANTHROPIC_API_KEY",
-    baseUrl: "https://api.anthropic.com",
-    healthcheck: "messages.create",
-  },
-  openrouter: {
-    providerId: "openrouter",
-    adapter: "openrouter",
-    authEnv: "OPENROUTER_API_KEY",
-    baseUrl: "https://openrouter.ai/api/v1",
-  },
-  openai: {
-    providerId: "openai-codex",
-    adapter: "openai-codex",
-    authEnv: "NEMORIS_OPENAI_API_KEY",
-    baseUrl: "https://api.openai.com/v1",
-  },
-  ollama: {
-    providerId: "ollama",
-    adapter: "ollama",
-    authEnv: "",
-    baseUrl: "http://localhost:11434",
-    healthcheck: "http://localhost:11434/api/tags",
-  },
-};
-
-const MODEL_ROLE_ORDER = ["cheap_interactive", "fallback", "manual_bump"];
-const PROVIDER_MODEL_PRESETS = {
-  anthropic: [
-    {
-      key: "haiku",
-      id: "anthropic/claude-haiku-4-5",
-      label: "Claude Haiku 4.5",
-      description: "Fastest and cheapest for interactive work.",
-    },
-    {
-      key: "sonnet",
-      id: "anthropic/claude-sonnet-4-6",
-      label: "Claude Sonnet 4.6",
-      description: "Balanced default for most serious work.",
-    },
-    {
-      key: "opus",
-      id: "anthropic/claude-opus-4-6",
-      label: "Claude Opus 4.6",
-      description: "Highest quality, slowest and most expensive.",
-    },
-  ],
-  openrouter: [
-    {
-      key: "haiku",
-      id: "openrouter/anthropic/claude-haiku-4-5",
-      label: "Claude Haiku 4.5",
-      description: "Lowest-cost OpenRouter default.",
-    },
-    {
-      key: "sonnet",
-      id: "openrouter/anthropic/claude-sonnet-4-6",
-      label: "Claude Sonnet 4.6",
-      description: "Strong general-purpose default.",
-    },
-    {
-      key: "gpt4o",
-      id: "openrouter/openai/gpt-4o",
-      label: "GPT-4o",
-      description: "Fast multimodal OpenAI route through OpenRouter.",
-    },
-    {
-      key: "opus",
-      id: "openrouter/anthropic/claude-opus-4-6",
-      label: "Claude Opus 4.6",
-      description: "Highest quality. Use when Sonnet isn't enough.",
-    },
-  ],
-  openai: [
-    {
-      key: "gpt41",
-      id: "openai-codex/gpt-4.1",
-      label: "GPT-4.1",
-      description: "Latest large-context default.",
-    },
-    {
-      key: "gpt4o",
-      id: "openai-codex/gpt-4o",
-      label: "GPT-4o",
-      description: "Fast multimodal fallback.",
-    },
-    {
-      key: "o4mini",
-      id: "openai-codex/o4-mini",
-      label: "o4-mini",
-      description: "Efficient reasoning path.",
-    },
-    {
-      key: "o3",
-      id: "openai-codex/o3",
-      label: "o3",
-      description: "Most capable reasoning option.",
-    },
-  ],
-};
-
-function stripProviderPrefix(provider, modelId) {
-  if (provider === "openrouter") {
-    return modelId.replace(/^openrouter\//, "");
-  }
-  if (provider === "openai") {
-    return modelId.replace(/^openai-codex\//, "");
-  }
-  if (provider === "anthropic") {
-    return modelId.replace(/^anthropic\//, "");
-  }
-  return modelId;
-}
-
-function ensureProviderModelPrefix(provider, modelId) {
-  const trimmed = String(modelId || "").trim();
-  if (!trimmed) return "";
-  if (provider === "openrouter") {
-    return trimmed.startsWith("openrouter/") ? trimmed : `openrouter/${trimmed}`;
-  }
-  if (provider === "openai") {
-    return trimmed.startsWith("openai-codex/") ? trimmed : `openai-codex/${trimmed}`;
-  }
-  if (provider === "anthropic") {
-    return trimmed.startsWith("anthropic/") ? trimmed : `anthropic/${trimmed}`;
-  }
-  return trimmed;
-}
-
-function buildProviderModelEntries(provider, selectedModels = []) {
-  const presets = PROVIDER_MODEL_PRESETS[provider] || [];
-  return selectedModels.map((id, index) => {
-    const preset = presets.find((item) => item.id === id);
-    return {
-      key: preset?.key || `model${index + 1}`,
-      id,
-      role: MODEL_ROLE_ORDER[index] || MODEL_ROLE_ORDER.at(-1),
-    };
-  });
-}
-
-function providerDisplayName(provider) {
-  if (provider === "openrouter") return "OpenRouter";
-  if (provider === "openai") return "OpenAI";
-  if (provider === "anthropic") return "Anthropic";
-  return provider;
-}
-
-async function fetchProviderModelIds(provider, key, { fetchImpl = globalThis.fetch } = {}) {
-  if (provider === "anthropic") {
-    return PROVIDER_MODEL_PRESETS.anthropic.map((item) => item.id);
-  }
-
-  const target = provider === "openrouter"
-    ? {
-        url: "https://openrouter.ai/api/v1/models",
-        headers: { authorization: `Bearer ${key}` },
-      }
-    : provider === "openai"
-      ? {
-          url: "https://api.openai.com/v1/models",
-          headers: { authorization: `Bearer ${key}` },
-        }
-      : null;
-
-  if (!target) {
-    return [];
-  }
-
-  try {
-    const response = await fetchImpl(target.url, {
-      method: "GET",
-      headers: target.headers,
-      signal: AbortSignal.timeout(10000),
-    });
-    const data = await response.json();
-    if (!response.ok) {
-      return [];
-    }
-    const ids = Array.isArray(data?.data)
-      ? data.data.map((item) => item?.id).filter(Boolean)
-      : [];
-    if (provider === "openrouter") {
-      return ids.map((id) => ensureProviderModelPrefix(provider, id));
-    }
-    if (provider === "openai") {
-      return ids.map((id) => ensureProviderModelPrefix(provider, id));
-    }
-    return ids;
-  } catch {
-    return [];
-  }
-}
-
-async function buildProviderSelectionOptions(provider, key, { fetchImpl = globalThis.fetch } = {}) {
-  if (provider === "openai") {
-    const discoveredModels = await fetchOpenAIModels(key, { fetchImpl });
-    return buildModelSelectionOptions({
-      provider,
-      discoveredModels,
-      includeKeep: false,
-      includeManual: true,
-    }).map((entry) => ({
-      value: entry.value,
-      label: entry.label,
-      description: entry.hint,
-    }));
-  }
-
-  const curated = PROVIDER_MODEL_PRESETS[provider] || [];
-  const available = new Set(await fetchProviderModelIds(provider, key, { fetchImpl }));
-  const selectable = curated.filter((item) => available.size === 0 || available.has(item.id));
-  const options = selectable.length > 0 ? selectable : curated;
-  return options.map((item) => ({
-    value: item.id,
-    label: item.label,
-    description: item.description,
-  }));
-}
-
-async function promptForProviderModels(provider, key, tui, { fetchImpl = globalThis.fetch } = {}) {
-  const { select, prompt, dim, cyan } = tui;
-  if (!select) return [];
-
-  const options = await buildProviderSelectionOptions(provider, key, { fetchImpl });
-  const chosen = [];
-  const manualOptionValue = provider === "openai" ? "__manual__" : "__custom__";
-  const defaultModelValue = options.find((item) => !String(item.value).startsWith("__"))?.value || "";
-
-  console.log(`\n  ${cyan(`Choose ${provider === "openrouter" ? "OpenRouter" : provider === "openai" ? "OpenAI" : "Anthropic"} models`)}`);
-  console.log(`  ${dim("Pick up to three models. The first is your default. The others are fallbacks when the default is slow or unavailable.")}`);
-
-  while (chosen.length < 3) {
-    const remaining = options.filter((item) => !chosen.includes(item.value));
-    const pickerOptions = remaining.map((item) => ({
-      label: item.label,
-      value: item.value,
-      description: item.description,
-    }));
-
-    if (chosen.length > 0) {
-      pickerOptions.push({
-        label: "Done",
-        value: "__done__",
-        description: "Continue setup with the models already selected.",
-      });
-    }
-
-    if (provider !== "openai") {
-      pickerOptions.push({
-        label: "Enter a different model name...",
-        value: manualOptionValue,
-        description: "Use a specific model id not shown in the curated list.",
-      });
-    }
-
-    const picked = await select(
-      chosen.length === 0 ? "Default model:" : `Add another model (${chosen.length}/3 selected):`,
-      pickerOptions,
-    );
-
-    if (picked === "__done__") {
-      break;
-    }
-
-    let modelId = picked;
-    if (picked === manualOptionValue) {
-      const custom = await prompt("Model id", stripProviderPrefix(provider, defaultModelValue));
-      modelId = ensureProviderModelPrefix(provider, custom);
-      if (!modelId) {
-        continue;
-      }
-    }
-
-    if (!chosen.includes(modelId)) {
-      chosen.push(modelId);
-    }
-  }
-
-  return chosen;
-}
-
-export function writeProviderConfigs(installDir, providerInput) {
-  const providersDir = path.join(installDir, "config", "providers");
-  fs.mkdirSync(providersDir, { recursive: true });
-  const selections = Array.isArray(providerInput)
-    ? Object.fromEntries(providerInput.map((id) => [id, []]))
-    : (providerInput || {});
-
-  for (const [provider, rawSelection] of Object.entries(selections)) {
-    const selection = Array.isArray(rawSelection)
-      ? { models: rawSelection }
-      : (rawSelection || {});
-    const baseConfig = PROVIDER_CONFIGS[provider] ?? {};
-    const providerId = baseConfig.providerId || provider;
-    const config = {
-      ...baseConfig,
-      ...("authRef" in selection ? { authRef: selection.authRef } : {}),
-      models: buildProviderModelEntries(provider, selection.models || []),
-    };
-    const content = providerTemplate(providerId, config);
-    fs.writeFileSync(path.join(providersDir, `${providerId}.toml`), content, "utf8");
-  }
-}
-
-export function writeRouter(installDir, providers, selectedModels = {}) {
-  const configDir = path.join(installDir, "config");
-  fs.mkdirSync(configDir, { recursive: true });
-  const content = routerTemplate({ ...providers, selectedModels });
-  fs.writeFileSync(path.join(configDir, "router.toml"), content, "utf8");
-}
-
-async function promptForProviderKey(provider, tui, validateApiKeyImpl = validateApiKey) {
-  const { promptSecret, bold, dim, green, red, yellow } = tui;
-  if (!promptSecret) return null;
-
-  while (true) {
-    if (provider === "anthropic") {
-      console.log(`\n  ${bold("Anthropic setup-token")} ${dim("(recommended if you have Claude Code)")}`);
-      console.log(`     1. Run: ${green("claude setup-token")} ${dim("(on any machine with Claude Code)")}`);
-      console.log(`     2. Paste the token here ${dim("(leave blank to skip)")}`);
-      console.log(`\n     ${dim("-- OR --")}\n`);
-      console.log(`     ${bold("API key")} ${dim("(from console.anthropic.com/settings/keys)")}`);
-    } else if (provider === "openai") {
-      console.log(`\n  ${bold("OpenAI API key")} ${dim("(from platform.openai.com/api-keys; leave blank to skip)")}`);
-    } else if (provider === "openrouter") {
-      console.log(`\n  ${bold("OpenRouter API key")} ${dim("(from openrouter.ai/keys; leave blank to skip)")}`);
-    }
-
-    const question = provider === "anthropic"
-      ? "Paste your Anthropic token"
-      : provider === "openrouter"
-        ? "Paste your OpenRouter key"
-        : "Paste your sk-... key";
-    const raw = await promptSecret(question);
-    const token = raw.trim();
-    if (!token) return null;
-
-    const format = validateApiKeyFormat(provider, token);
-    if (!format.ok) {
-      console.log(`  ${red("✗")} ${format.error}`);
-      continue;
-    }
-
-    console.log(`  ${dim("Verifying key...")}`);
-    const slowValidationNotice = setTimeout(() => {
-      console.log(`  ${dim("This may take a few seconds...")}`);
-    }, 3000);
-    let result;
-    try {
-      result = await validateApiKeyImpl(provider, token);
-    } finally {
-      clearTimeout(slowValidationNotice);
-    }
-    if (result.ok) {
-      const providerLabel = provider === "anthropic" ? "Anthropic" : provider === "openrouter" ? "OpenRouter" : "OpenAI";
-      console.log(`  ${green("✓")} ${providerLabel} key verified`);
-      return token;
-    }
-
-    if (result.status === 401 || result.status === 403) {
-      console.log(`  ${red("✗")} Authentication failed (${result.status}). Try again.`);
-      continue;
-    }
-
-    const detail = result.status ? `HTTP ${result.status}` : (result.error || "request failed");
-    console.log(`  ${yellow("!")} Couldn't verify the key (${detail}). Check the key and try again, or press Enter to skip.`);
-  }
-}
-
-async function confirmLocalOnlySetup(tui) {
-  const { confirm, yellow = (value) => value, dim = (value) => value } = tui;
-  if (!confirm) {
-    return true;
-  }
-
-  console.log(`\n  ${yellow("⚠")} You haven't configured any cloud providers.`);
-  console.log(`  ${dim("Your agent will only use local models (Ollama).")}`);
-  return confirm("Continue anyway?", false);
-}
-
-async function maybeResolveOpenAIOAuth({
-  tui,
-  enableOpenAIOAuthChoice = false,
-  openAIOAuthImpl = initiateOpenAICodexOAuthFlow,
-}) {
-  const authProfilesPath = resolveAuthProfilesPath();
-  const existingProfile = getAuthProfile(OPENAI_CODEX_DEFAULT_PROFILE_ID, authProfilesPath);
-  const inspection = inspectOpenAICodexProfile(existingProfile, { now: Date.now() });
-
-  if (inspection.state === "usable_token" || inspection.state === "refresh_needed") {
-    const resolved = await resolveOpenAICodexAccess(OPENAI_CODEX_DEFAULT_PROFILE_ID, {
-      filePath: authProfilesPath,
-    });
-    return {
-      authRef: `profile:${OPENAI_CODEX_DEFAULT_PROFILE_ID}`,
-      token: resolved.token,
-      mode: "oauth",
-    };
-  }
-
-  if (!enableOpenAIOAuthChoice || !tui?.select) {
-    return null;
-  }
-
-  const method = await tui.select("OpenAI auth method:", [
-    {
-      label: "API key",
-      value: "api_key",
-      description: "Paste an OpenAI API key from platform.openai.com.",
-    },
-    {
-      label: "ChatGPT OAuth",
-      value: "oauth",
-      description: "Open browser login and store a refreshable local profile.",
-    },
-  ]);
-
-  if (method !== "oauth") {
-    return null;
-  }
-
-  const profile = await openAIOAuthImpl({
-    filePath: authProfilesPath,
-    promptForPasteImpl: async (message) => (tui.prompt ? tui.prompt(message, "") : ""),
-  });
-
-  return {
-    authRef: `profile:${OPENAI_CODEX_DEFAULT_PROFILE_ID}`,
-    token: profile.access,
-    mode: "oauth",
-  };
-}
-
-/**
- * @param {string} installDir
- * @param {object} [options]
- * @param {object} [options.tui]
- * @param {object} [options.detectionCache]
- * @param {Function} [options.validateApiKeyImpl]
- * @returns {Promise<{ providers: string[], providerFlags: object, keys: object }>}
- */
-export async function runAuthPhase(installDir, options = {}) {
-  const {
-    tui,
-    detectionCache,
-    validateApiKeyImpl = validateApiKey,
-    fetchImpl = globalThis.fetch,
-    providerOrder = ["openrouter", "anthropic", "openai"],
-    enableOpenAIOAuthChoice = false,
-    openAIOAuthImpl = initiateOpenAICodexOAuthFlow,
-  } = options;
-  const existingKeys = detectionCache?.rawKeys || detectExistingKeys();
-  const ollamaResult = detectionCache?.ollamaResult || await detectOllama();
-  const keys = { ...existingKeys };
-  const prevalidatedKeys = new Set();
-  const selectedModels = {};
-  const providerAuthRefs = {};
-  const providerSecrets = {};
-
-  if (tui) {
-    let promptingComplete = false;
-    while (!promptingComplete) {
-      for (const provider of providerOrder) {
-        if (keys[provider]) continue;
-        if (provider === "openai") {
-          const oauthResult = await maybeResolveOpenAIOAuth({
-            tui,
-            enableOpenAIOAuthChoice,
-            openAIOAuthImpl,
-          });
-          if (oauthResult) {
-            providerAuthRefs.openai = oauthResult.authRef;
-            providerSecrets.openai = oauthResult.token;
-            continue;
-          }
-        }
-        keys[provider] = await promptForProviderKey(provider, tui, validateApiKeyImpl);
-        if (keys[provider]) {
-          prevalidatedKeys.add(provider);
-        }
-      }
-
-      const hasCloudProvider = Boolean(
-        keys.openrouter || keys.anthropic || keys.openai || providerAuthRefs.openai
-      );
-      if (hasCloudProvider || !ollamaResult.ok) {
-        promptingComplete = true;
-        continue;
-      }
-
-      const continueWithLocalOnly = await confirmLocalOnlySetup(tui);
-      if (continueWithLocalOnly) {
-        promptingComplete = true;
-      }
-    }
-  }
-
-  const validatedKeys = {};
-  const providerFlags = { anthropic: false, openrouter: false, openai: false, ollama: ollamaResult.ok };
-
-  for (const [provider, key] of Object.entries(keys)) {
-    if (!key) continue;
-    const format = validateApiKeyFormat(provider, key);
-    if (!format.ok) continue;
-    const result = prevalidatedKeys.has(provider)
-      ? { ok: true, status: 200 }
-      : await validateApiKeyImpl(provider, key);
-    if (!result.ok) continue;
-
-    validatedKeys[provider] = key;
-    providerSecrets[provider] = key;
-    if (provider in providerFlags) {
-      providerFlags[provider] = true;
-    }
-  }
-
-  if (providerAuthRefs.openai) {
-    providerFlags.openai = true;
-  }
-
-  if (tui) {
-    for (const provider of ["openrouter", "anthropic", "openai"]) {
-      const providerToken = providerSecrets[provider];
-      if (!providerToken) continue;
-      selectedModels[provider] = await promptForProviderModels(provider, providerToken, tui, { fetchImpl });
-    }
-  }
-
-  const envKeys = {};
-  if (validatedKeys.anthropic) {
-    envKeys.NEMORIS_ANTHROPIC_API_KEY = validatedKeys.anthropic;
-  }
-  if (validatedKeys.openai) {
-    envKeys.NEMORIS_OPENAI_API_KEY = validatedKeys.openai;
-  }
-  if (validatedKeys.openrouter) {
-    envKeys.OPENROUTER_API_KEY = validatedKeys.openrouter;
-  }
-  if (Object.keys(envKeys).length > 0) {
-    writeEnvFile(installDir, envKeys);
-  }
-
-  const providerIds = resolveProviders({
-    anthropic: validatedKeys.anthropic || null,
-    openrouter: validatedKeys.openrouter || null,
-    openai: validatedKeys.openai || providerAuthRefs.openai || null,
-    ollama: ollamaResult.ok,
-  });
-  writeProviderConfigs(installDir, Object.fromEntries(providerIds.map((id) => [id, {
-    models: selectedModels[id] || [],
-    ...(providerAuthRefs[id] ? { authRef: providerAuthRefs[id] } : {}),
-  }])));
-  writeRouter(installDir, providerFlags, selectedModels);
-
-  return { providers: providerIds, providerFlags, keys: validatedKeys, selectedModels };
-}
+/**
+ * Auth phase — orchestrates key detection, validation, .env writing,
+ * and provider/router TOML generation.
+ *
+ * Phase 3 of the onboarding wizard. Zero LLM tokens consumed; does network
+ * probes for health checks only.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { providerTemplate, routerTemplate } from "../templates.js";
+import {
+  detectExistingKeys,
+  validateApiKey,
+  validateApiKeyFormat,
+  writeEnvFile,
+  resolveProviders
+} from "../auth/api-key.js";
+import { detectOllama } from "../auth/ollama-detect.js";
+import {
+  initiateOpenAICodexOAuthFlow,
+  inspectOpenAICodexProfile,
+  OPENAI_CODEX_DEFAULT_PROFILE_ID,
+  resolveOpenAICodexAccess,
+} from "../../auth/openai-codex-oauth.js";
+import { getAuthProfile, resolveAuthProfilesPath } from "../../auth/auth-profiles.js";
+
+const PROVIDER_CONFIGS = {
+  anthropic: {
+    providerId: "anthropic",
+    adapter: "anthropic",
+    authEnv: "NEMORIS_ANTHROPIC_API_KEY",
+    baseUrl: "https://api.anthropic.com",
+    healthcheck: "messages.create",
+  },
+  openrouter: {
+    providerId: "openrouter",
+    adapter: "openrouter",
+    authEnv: "OPENROUTER_API_KEY",
+    baseUrl: "https://openrouter.ai/api/v1",
+  },
+  openai: {
+    providerId: "openai-codex",
+    adapter: "openai-codex",
+    authEnv: "NEMORIS_OPENAI_API_KEY",
+    baseUrl: "https://api.openai.com/v1",
+  },
+  ollama: {
+    providerId: "ollama",
+    adapter: "ollama",
+    authEnv: "",
+    baseUrl: "http://localhost:11434",
+    healthcheck: "http://localhost:11434/api/tags",
+  },
+};
+
+const MODEL_ROLE_ORDER = ["cheap_interactive", "fallback", "manual_bump"];
+const PROVIDER_MODEL_PRESETS = {
+  anthropic: [
+    {
+      key: "haiku",
+      id: "anthropic/claude-haiku-4-5",
+      label: "Claude Haiku 4.5",
+      description: "Fastest and cheapest for interactive work.",
+    },
+    {
+      key: "sonnet",
+      id: "anthropic/claude-sonnet-4-6",
+      label: "Claude Sonnet 4.6",
+      description: "Balanced default for most serious work.",
+    },
+    {
+      key: "opus",
+      id: "anthropic/claude-opus-4-6",
+      label: "Claude Opus 4.6",
+      description: "Highest quality, slowest and most expensive.",
+    },
+  ],
+  openrouter: [
+    {
+      key: "haiku",
+      id: "openrouter/anthropic/claude-haiku-4-5",
+      label: "Claude Haiku 4.5",
+      description: "Lowest-cost OpenRouter default.",
+    },
+    {
+      key: "sonnet",
+      id: "openrouter/anthropic/claude-sonnet-4-6",
+      label: "Claude Sonnet 4.6",
+      description: "Strong general-purpose default.",
+    },
+    {
+      key: "gpt4o",
+      id: "openrouter/openai/gpt-4o",
+      label: "GPT-4o",
+      description: "Fast multimodal OpenAI route through OpenRouter.",
+    },
+    {
+      key: "opus",
+      id: "openrouter/anthropic/claude-opus-4-6",
+      label: "Claude Opus 4.6",
+      description: "Highest quality. Use when Sonnet isn't enough.",
+    },
+  ],
+  openai: [
+    {
+      key: "gpt41",
+      id: "openai-codex/gpt-4.1",
+      label: "GPT-4.1",
+      description: "Latest large-context default.",
+    },
+    {
+      key: "gpt4o",
+      id: "openai-codex/gpt-4o",
+      label: "GPT-4o",
+      description: "Fast multimodal fallback.",
+    },
+    {
+      key: "o4mini",
+      id: "openai-codex/o4-mini",
+      label: "o4-mini",
+      description: "Efficient reasoning path.",
+    },
+    {
+      key: "o3",
+      id: "openai-codex/o3",
+      label: "o3",
+      description: "Most capable reasoning option.",
+    },
+  ],
+};
+
+function stripProviderPrefix(provider, modelId) {
+  if (provider === "openrouter") {
+    return modelId.replace(/^openrouter\//, "");
+  }
+  if (provider === "openai") {
+    return modelId.replace(/^openai-codex\//, "");
+  }
+  if (provider === "anthropic") {
+    return modelId.replace(/^anthropic\//, "");
+  }
+  return modelId;
+}
+
+function ensureProviderModelPrefix(provider, modelId) {
+  const trimmed = String(modelId || "").trim();
+  if (!trimmed) return "";
+  if (provider === "openrouter") {
+    return trimmed.startsWith("openrouter/") ? trimmed : `openrouter/${trimmed}`;
+  }
+  if (provider === "openai") {
+    return trimmed.startsWith("openai-codex/") ? trimmed : `openai-codex/${trimmed}`;
+  }
+  if (provider === "anthropic") {
+    return trimmed.startsWith("anthropic/") ? trimmed : `anthropic/${trimmed}`;
+  }
+  return trimmed;
+}
+
+function buildProviderModelEntries(provider, selectedModels = []) {
+  const presets = PROVIDER_MODEL_PRESETS[provider] || [];
+  return selectedModels.map((id, index) => {
+    const preset = presets.find((item) => item.id === id);
+    return {
+      key: preset?.key || `model${index + 1}`,
+      id,
+      role: MODEL_ROLE_ORDER[index] || MODEL_ROLE_ORDER.at(-1),
+    };
+  });
+}
+
+function providerDisplayName(provider) {
+  if (provider === "openrouter") return "OpenRouter";
+  if (provider === "openai") return "OpenAI";
+  if (provider === "anthropic") return "Anthropic";
+  return provider;
+}
+
+async function fetchProviderModelIds(provider, key, { fetchImpl = globalThis.fetch } = {}) {
+  const targets = {
+    anthropic: {
+      url: "https://api.anthropic.com/v1/models",
+      headers: { "x-api-key": key, "anthropic-version": "2023-06-01" },
+    },
+    openrouter: {
+      url: "https://openrouter.ai/api/v1/models",
+      headers: { authorization: `Bearer ${key}` },
+    },
+    openai: {
+      url: "https://api.openai.com/v1/models",
+      headers: { authorization: `Bearer ${key}` },
+    },
+  };
+
+  const target = targets[provider];
+  if (!target) return [];
+
+  try {
+    const response = await fetchImpl(target.url, {
+      method: "GET",
+      headers: target.headers,
+      signal: AbortSignal.timeout(10000),
+    });
+    const data = await response.json();
+    if (!response.ok) return PROVIDER_MODEL_PRESETS[provider]?.map((item) => item.id) ?? [];
+    const ids = Array.isArray(data?.data)
+      ? data.data.map((item) => item?.id).filter(Boolean)
+      : [];
+    return ids.map((id) => ensureProviderModelPrefix(provider, id));
+  } catch {
+    return PROVIDER_MODEL_PRESETS[provider]?.map((item) => item.id) ?? [];
+  }
+}
+
+async function buildProviderSelectionOptions(provider, key, { fetchImpl = globalThis.fetch } = {}) {
+  const curated = PROVIDER_MODEL_PRESETS[provider] || [];
+  const fetched = await fetchProviderModelIds(provider, key, { fetchImpl });
+  const fetchedSet = new Set(fetched);
+
+  // Curated models that exist in the fetched list (fall back to all curated if fetch failed)
+  const curatedAvailable = fetched.length > 0
+    ? curated.filter((item) => fetchedSet.has(item.id))
+    : curated;
+  const curatedIds = new Set(curatedAvailable.map((item) => item.id));
+
+  // Remaining fetched models not already shown as curated
+  const extra = fetched
+    .filter((id) => !curatedIds.has(id))
+    .map((id) => {
+      const displayId = id
+        .replace(/^openrouter\//, "")
+        .replace(/^openai-codex\//, "")
+        .replace(/^anthropic\//, "");
+      return { value: id, label: displayId, description: "available from provider" };
+    });
+
+  return [
+    ...curatedAvailable.map((item) => ({ value: item.id, label: item.label, description: item.description })),
+    ...extra,
+    { value: "__custom__", label: "Enter a different model name...", description: "Use a specific model id not shown in the list." },
+  ];
+}
+
+async function promptForProviderModels(provider, key, tui, { fetchImpl = globalThis.fetch } = {}) {
+  const { select, prompt, dim, cyan } = tui;
+  if (!select) return [];
+
+  const options = await buildProviderSelectionOptions(provider, key, { fetchImpl });
+  const chosen = [];
+  const manualOptionValue = "__custom__";
+  const defaultModelValue = options.find((item) => !String(item.value).startsWith("__"))?.value || "";
+
+  console.log(`\n  ${cyan(`Choose ${provider === "openrouter" ? "OpenRouter" : provider === "openai" ? "OpenAI" : "Anthropic"} models`)}`);
+  console.log(`  ${dim("Pick up to three models. The first is your default. The others are fallbacks when the default is slow or unavailable.")}`);
+
+  while (chosen.length < 3) {
+    const remaining = options.filter((item) => !chosen.includes(item.value));
+    const pickerOptions = remaining.map((item) => ({
+      label: item.label,
+      value: item.value,
+      description: item.description,
+    }));
+
+    if (chosen.length > 0) {
+      // Insert "Done" before the custom-entry option at the end
+      const customIndex = pickerOptions.findIndex((item) => item.value === "__custom__");
+      const doneOption = { label: "Done", value: "__done__", description: "Continue setup with the models already selected." };
+      if (customIndex >= 0) {
+        pickerOptions.splice(customIndex, 0, doneOption);
+      } else {
+        pickerOptions.push(doneOption);
+      }
+    }
+
+    const picked = await select(
+      chosen.length === 0 ? "Default model:" : `Add another model (${chosen.length}/3 selected):`,
+      pickerOptions,
+    );
+
+    if (picked === "__done__") {
+      break;
+    }
+
+    let modelId = picked;
+    if (picked === manualOptionValue) {
+      const custom = await prompt("Model id", stripProviderPrefix(provider, defaultModelValue));
+      modelId = ensureProviderModelPrefix(provider, custom);
+      if (!modelId) {
+        continue;
+      }
+    }
+
+    if (!chosen.includes(modelId)) {
+      chosen.push(modelId);
+    }
+  }
+
+  return chosen;
+}
+
+export function writeProviderConfigs(installDir, providerInput) {
+  const providersDir = path.join(installDir, "config", "providers");
+  fs.mkdirSync(providersDir, { recursive: true });
+  const selections = Array.isArray(providerInput)
+    ? Object.fromEntries(providerInput.map((id) => [id, []]))
+    : (providerInput || {});
+
+  for (const [provider, rawSelection] of Object.entries(selections)) {
+    const selection = Array.isArray(rawSelection)
+      ? { models: rawSelection }
+      : (rawSelection || {});
+    const baseConfig = PROVIDER_CONFIGS[provider] ?? {};
+    const providerId = baseConfig.providerId || provider;
+    const config = {
+      ...baseConfig,
+      ...("authRef" in selection ? { authRef: selection.authRef } : {}),
+      models: buildProviderModelEntries(provider, selection.models || []),
+    };
+    const content = providerTemplate(providerId, config);
+    fs.writeFileSync(path.join(providersDir, `${providerId}.toml`), content, "utf8");
+  }
+}
+
+export function writeRouter(installDir, providers, selectedModels = {}) {
+  const configDir = path.join(installDir, "config");
+  fs.mkdirSync(configDir, { recursive: true });
+  const content = routerTemplate({ ...providers, selectedModels });
+  fs.writeFileSync(path.join(configDir, "router.toml"), content, "utf8");
+}
+
+async function promptForProviderKey(provider, tui, validateApiKeyImpl = validateApiKey) {
+  const { promptSecret, bold, dim, green, red, yellow } = tui;
+  if (!promptSecret) return null;
+
+  while (true) {
+    if (provider === "anthropic") {
+      console.log(`\n  ${bold("Anthropic setup-token")} ${dim("(recommended if you have Claude Code)")}`);
+      console.log(`     1. Run: ${green("claude setup-token")} ${dim("(on any machine with Claude Code)")}`);
+      console.log(`     2. Paste the token here ${dim("(leave blank to skip)")}`);
+      console.log(`\n     ${dim("-- OR --")}\n`);
+      console.log(`     ${bold("API key")} ${dim("(from console.anthropic.com/settings/keys)")}`);
+    } else if (provider === "openai") {
+      console.log(`\n  ${bold("OpenAI API key")} ${dim("(from platform.openai.com/api-keys; leave blank to skip)")}`);
+    } else if (provider === "openrouter") {
+      console.log(`\n  ${bold("OpenRouter API key")} ${dim("(from openrouter.ai/keys; leave blank to skip)")}`);
+    }
+
+    const question = provider === "anthropic"
+      ? "Paste your Anthropic token"
+      : provider === "openrouter"
+        ? "Paste your OpenRouter key"
+        : "Paste your sk-... key";
+    const raw = await promptSecret(question);
+    const token = raw.trim();
+    if (!token) return null;
+
+    const format = validateApiKeyFormat(provider, token);
+    if (!format.ok) {
+      console.log(`  ${red("✗")} ${format.error}`);
+      continue;
+    }
+
+    console.log(`  ${dim("Verifying key...")}`);
+    const slowValidationNotice = setTimeout(() => {
+      console.log(`  ${dim("This may take a few seconds...")}`);
+    }, 3000);
+    let result;
+    try {
+      result = await validateApiKeyImpl(provider, token);
+    } finally {
+      clearTimeout(slowValidationNotice);
+    }
+    if (result.ok) {
+      const providerLabel = provider === "anthropic" ? "Anthropic" : provider === "openrouter" ? "OpenRouter" : "OpenAI";
+      console.log(`  ${green("✓")} ${providerLabel} key verified`);
+      return token;
+    }
+
+    if (result.status === 401 || result.status === 403) {
+      console.log(`  ${red("✗")} Authentication failed (${result.status}). Try again.`);
+      continue;
+    }
+
+    const detail = result.status ? `HTTP ${result.status}` : (result.error || "request failed");
+    console.log(`  ${yellow("!")} Couldn't verify the key (${detail}). Check the key and try again, or press Enter to skip.`);
+  }
+}
+
+async function confirmLocalOnlySetup(tui) {
+  const { confirm, yellow = (value) => value, dim = (value) => value } = tui;
+  if (!confirm) {
+    return true;
+  }
+
+  console.log(`\n  ${yellow("⚠")} You haven't configured any cloud providers.`);
+  console.log(`  ${dim("Your agent will only use local models (Ollama).")}`);
+  return confirm("Continue anyway?", false);
+}
+
+async function maybeResolveOpenAIOAuth({
+  tui,
+  enableOpenAIOAuthChoice = false,
+  openAIOAuthImpl = initiateOpenAICodexOAuthFlow,
+}) {
+  const authProfilesPath = resolveAuthProfilesPath();
+  const existingProfile = getAuthProfile(OPENAI_CODEX_DEFAULT_PROFILE_ID, authProfilesPath);
+  const inspection = inspectOpenAICodexProfile(existingProfile, { now: Date.now() });
+
+  if (inspection.state === "usable_token" || inspection.state === "refresh_needed") {
+    const resolved = await resolveOpenAICodexAccess(OPENAI_CODEX_DEFAULT_PROFILE_ID, {
+      filePath: authProfilesPath,
+    });
+    return {
+      authRef: `profile:${OPENAI_CODEX_DEFAULT_PROFILE_ID}`,
+      token: resolved.token,
+      mode: "oauth",
+    };
+  }
+
+  if (!enableOpenAIOAuthChoice || !tui?.select) {
+    return null;
+  }
+
+  const method = await tui.select("OpenAI auth method:", [
+    {
+      label: "API key",
+      value: "api_key",
+      description: "Paste an OpenAI API key from platform.openai.com.",
+    },
+    {
+      label: "ChatGPT OAuth",
+      value: "oauth",
+      description: "Open browser login and store a refreshable local profile.",
+    },
+  ]);
+
+  if (method !== "oauth") {
+    return null;
+  }
+
+  const profile = await openAIOAuthImpl({
+    filePath: authProfilesPath,
+    promptForPasteImpl: async (message) => (tui.prompt ? tui.prompt(message, "") : ""),
+  });
+
+  return {
+    authRef: `profile:${OPENAI_CODEX_DEFAULT_PROFILE_ID}`,
+    token: profile.access,
+    mode: "oauth",
+  };
+}
+
+/**
+ * @param {string} installDir
+ * @param {object} [options]
+ * @param {object} [options.tui]
+ * @param {object} [options.detectionCache]
+ * @param {Function} [options.validateApiKeyImpl]
+ * @returns {Promise<{ providers: string[], providerFlags: object, keys: object }>}
+ */
+export async function runAuthPhase(installDir, options = {}) {
+  const {
+    tui,
+    detectionCache,
+    validateApiKeyImpl = validateApiKey,
+    fetchImpl = globalThis.fetch,
+    providerOrder = ["openrouter", "anthropic", "openai"],
+    enableOpenAIOAuthChoice = false,
+    openAIOAuthImpl = initiateOpenAICodexOAuthFlow,
+  } = options;
+  const existingKeys = detectionCache?.rawKeys || detectExistingKeys();
+  const ollamaResult = detectionCache?.ollamaResult || await detectOllama();
+  const keys = { ...existingKeys };
+  const prevalidatedKeys = new Set();
+  const selectedModels = {};
+  const providerAuthRefs = {};
+  const providerSecrets = {};
+
+  if (tui) {
+    let promptingComplete = false;
+    while (!promptingComplete) {
+      for (const provider of providerOrder) {
+        if (keys[provider]) continue;
+        if (provider === "openai") {
+          const oauthResult = await maybeResolveOpenAIOAuth({
+            tui,
+            enableOpenAIOAuthChoice,
+            openAIOAuthImpl,
+          });
+          if (oauthResult) {
+            providerAuthRefs.openai = oauthResult.authRef;
+            providerSecrets.openai = oauthResult.token;
+            continue;
+          }
+        }
+        keys[provider] = await promptForProviderKey(provider, tui, validateApiKeyImpl);
+        if (keys[provider]) {
+          prevalidatedKeys.add(provider);
+        }
+      }
+
+      const hasCloudProvider = Boolean(
+        keys.openrouter || keys.anthropic || keys.openai || providerAuthRefs.openai
+      );
+      if (hasCloudProvider || !ollamaResult.ok) {
+        promptingComplete = true;
+        continue;
+      }
+
+      const continueWithLocalOnly = await confirmLocalOnlySetup(tui);
+      if (continueWithLocalOnly) {
+        promptingComplete = true;
+      }
+    }
+  }
+
+  const validatedKeys = {};
+  const providerFlags = { anthropic: false, openrouter: false, openai: false, ollama: ollamaResult.ok };
+
+  for (const [provider, key] of Object.entries(keys)) {
+    if (!key) continue;
+    const format = validateApiKeyFormat(provider, key);
+    if (!format.ok) continue;
+    const result = prevalidatedKeys.has(provider)
+      ? { ok: true, status: 200 }
+      : await validateApiKeyImpl(provider, key);
+    if (!result.ok) continue;
+
+    validatedKeys[provider] = key;
+    providerSecrets[provider] = key;
+    if (provider in providerFlags) {
+      providerFlags[provider] = true;
+    }
+  }
+
+  if (providerAuthRefs.openai) {
+    providerFlags.openai = true;
+  }
+
+  if (tui) {
+    for (const provider of ["openrouter", "anthropic", "openai"]) {
+      const providerToken = providerSecrets[provider];
+      if (!providerToken) continue;
+      selectedModels[provider] = await promptForProviderModels(provider, providerToken, tui, { fetchImpl });
+    }
+  }
+
+  const envKeys = {};
+  if (validatedKeys.anthropic) {
+    envKeys.NEMORIS_ANTHROPIC_API_KEY = validatedKeys.anthropic;
+  }
+  if (validatedKeys.openai) {
+    envKeys.NEMORIS_OPENAI_API_KEY = validatedKeys.openai;
+  }
+  if (validatedKeys.openrouter) {
+    envKeys.OPENROUTER_API_KEY = validatedKeys.openrouter;
+  }
+  if (Object.keys(envKeys).length > 0) {
+    writeEnvFile(installDir, envKeys);
+  }
+
+  const providerIds = resolveProviders({
+    anthropic: validatedKeys.anthropic || null,
+    openrouter: validatedKeys.openrouter || null,
+    openai: validatedKeys.openai || providerAuthRefs.openai || null,
+    ollama: ollamaResult.ok,
+  });
+  writeProviderConfigs(installDir, Object.fromEntries(providerIds.map((id) => [id, {
+    models: selectedModels[id] || [],
+    ...(providerAuthRefs[id] ? { authRef: providerAuthRefs[id] } : {}),
+  }])));
+  writeRouter(installDir, providerFlags, selectedModels);
+
+  return { providers: providerIds, providerFlags, keys: validatedKeys, selectedModels };
+}