omegon 0.6.3 → 0.6.4

package/extensions/lib/model-routing.ts

@@ -13,7 +13,12 @@ import { PREFERRED_ORDER } from "./local-models.ts";
 // ---------------------------------------------------------------------------
 
 export type ModelTier = "local" | "retribution" | "victory" | "gloriana";
-export type ProviderName = "openai" | "anthropic" | "local";
+/**
+ * Well-known provider names for routing policy ordering and preference.
+ * Any string is accepted at runtime (unknown providers participate in
+ * capability-based matching) but these have explicit routing support.
+ */
+export type ProviderName = "anthropic" | "openai" | "github-copilot" | "google" | "amazon-bedrock" | "azure-openai-responses" | "xai" | "groq" | "mistral" | "openrouter" | "local" | (string & {});
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high";
 export type CapabilityRole = "archmagos" | "magos" | "adept" | "servitor" | "servoskull";
 export type CandidateSource = "upstream" | "local";
@@ -164,19 +169,101 @@ const ROLE_DISPLAY_LABELS: Record<CapabilityRole, string> = {
 };
 
 // ---------------------------------------------------------------------------
-// Anthropic/OpenAI defaults
+// Universal model-to-tier classification (provider-transparent)
+// ---------------------------------------------------------------------------
+// These patterns match model IDs regardless of provider. A github-copilot
+// model "claude-opus-4-6" matches the same rules as anthropic's.
+// Order within each tier matters — earlier entries are preferred.
 // ---------------------------------------------------------------------------
 
+interface TierRule {
+  exact?: string;
+  prefix?: string;
+  weight: CandidateWeight;
+  maxThinking: ThinkingLevel;
+  source: CandidateSource;
+}
+
+const TIER_RULES: Record<Exclude<ModelTier, "local">, TierRule[]> = {
+  gloriana: [
+    { prefix: "claude-opus", weight: "heavy", maxThinking: "high", source: "upstream" },
+    { exact: "gpt-5.4", weight: "heavy", maxThinking: "high", source: "upstream" },
+    { prefix: "gpt-5.4-", weight: "heavy", maxThinking: "high", source: "upstream" },
+    { prefix: "gemini-3-pro", weight: "heavy", maxThinking: "high", source: "upstream" },
+    { prefix: "gemini-3.1-pro", weight: "heavy", maxThinking: "high", source: "upstream" },
+  ],
+  victory: [
+    { prefix: "claude-sonnet", weight: "normal", maxThinking: "high", source: "upstream" },
+    { prefix: "gpt-5.3-codex", weight: "normal", maxThinking: "medium", source: "upstream" },
+    { exact: "gpt-5.3", weight: "normal", maxThinking: "medium", source: "upstream" },
+    { prefix: "gpt-5.2-codex", weight: "normal", maxThinking: "medium", source: "upstream" },
+    { exact: "gpt-5.2", weight: "normal", maxThinking: "medium", source: "upstream" },
+    { prefix: "gemini-3-flash", weight: "normal", maxThinking: "medium", source: "upstream" },
+    { prefix: "gemini-2.5-pro", weight: "normal", maxThinking: "medium", source: "upstream" },
+    { prefix: "grok-", weight: "normal", maxThinking: "medium", source: "upstream" },
+  ],
+  retribution: [
+    { prefix: "claude-haiku", weight: "light", maxThinking: "low", source: "upstream" },
+    { prefix: "gpt-5.1-codex", weight: "light", maxThinking: "low", source: "upstream" },
+    { exact: "gpt-5.1", weight: "light", maxThinking: "low", source: "upstream" },
+    { prefix: "gpt-5-mini", weight: "light", maxThinking: "low", source: "upstream" },
+    { prefix: "gpt-5-nano", weight: "light", maxThinking: "low", source: "upstream" },
+    { prefix: "gemini-2.0-flash", weight: "light", maxThinking: "low", source: "upstream" },
+    { prefix: "mistral-large", weight: "light", maxThinking: "low", source: "upstream" },
+    { prefix: "codestral", weight: "light", maxThinking: "low", source: "upstream" },
+  ],
+};
+
+// Legacy aliases — used only by matchAnthropicTier/matchOpenAITier for
+// backward compat with operator profiles that reference these constants.
 const ANTHROPIC_TIER_PREFIXES: Record<Exclude<ModelTier, "local">, string[]> = {
   retribution: ["claude-haiku"],
   victory: ["claude-sonnet"],
   gloriana: ["claude-opus"],
 };
 
+// Deprecated models that should never be selected even if the provider
+// still lists them. Prevents routing to dead or EOL endpoints.
+// Updated 2026-03-14: GPT-4.1, GPT-4.1 mini, o4-mini retired Feb 13 2026.
+const DEPRECATED_MODELS = new Set([
+  "gpt-4o", "gpt-4o-mini",
+  "gpt-4-turbo", "gpt-4",
+  "gpt-3.5-turbo",
+  "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano",
+  "o4-mini",
+  "gpt-5", "gpt-5-instant", "gpt-5-thinking",  // retired Feb 13 2026
+  "claude-3-haiku-20240307", "claude-3-sonnet-20240229", "claude-3-opus-20240229",
+  "claude-3-5-sonnet-20240620",  // ancient snapshots
+]);
+
+// o3 is a specialized reasoning model — not suitable as a general-purpose
+// archmagos candidate. It belongs in a dedicated "reasoning" role if needed.
+
+/**
+ * Filter deprecated models from a registry snapshot.
+ *
+ * Call this on `getAvailable()` output before passing to `resolveTier()`.
+ * Centralizes deprecation logic so callsites don't need to know the list.
+ */
+export function filterDeprecated(models: RegistryModel[]): RegistryModel[] {
+  return models.filter((m) => !DEPRECATED_MODELS.has(m.id));
+}
+
+/**
+ * Get the viable model pool: auth'd + non-deprecated.
+ *
+ * Single entry point for all routing callsites. Uses `getAvailable()` (only
+ * models with configured auth) then strips deprecated models.
+ *
+ * Pass the result to `resolveTier()`, `getDefaultCapabilityProfile()`, etc.
+ */
+export function getViableModels(registry: { getAvailable(): { id: string; provider: string }[] }): RegistryModel[] {
+  return filterDeprecated(registry.getAvailable() as unknown as RegistryModel[]);
+}
 const OPENAI_TIER_MODELS: Record<Exclude<ModelTier, "local">, string[]> = {
-  retribution: ["gpt-5.1-codex", "gpt-4o-mini", "gpt-4.1-mini"],
-  victory: ["gpt-5.3-codex-spark", "gpt-4.1", "gpt-4o"],
-  gloriana: ["gpt-5.4", "gpt-4.5", "o3"],
+  retribution: ["gpt-5.1-codex", "gpt-5.1"],
+  victory: ["gpt-5.3-codex-spark", "gpt-5.3", "gpt-5.2-codex", "gpt-5.2"],
+  gloriana: ["gpt-5.4"],
 };
 
 // ---------------------------------------------------------------------------
@@ -218,18 +305,20 @@ function matchAnthropicTier(models: RegistryModel[], tier: Exclude<ModelTier, "l
 function matchOpenAITier(models: RegistryModel[], tier: Exclude<ModelTier, "local">): RegistryModel | undefined {
   const exactIds = OPENAI_TIER_MODELS[tier];
   for (const modelId of exactIds) {
+    if (DEPRECATED_MODELS.has(modelId)) continue;
     const match = models.find((m) => m.provider === "openai" && m.id === modelId);
     if (match) return match;
   }
   const exactIdSet = new Set(exactIds);
   const prefixFallbacks: Record<string, string[]> = {
-    retribution: ["gpt-4o-mini-", "gpt-4.1-mini-"],
-    victory: ["gpt-4o-", "gpt-4.1-"],
-    gloriana: ["gpt-4.5-", "o3-", "gpt-5."],
+    retribution: ["gpt-5.1-"],
+    victory: ["gpt-5.2-", "gpt-5.3-"],
+    gloriana: ["gpt-5.4-"],
   };
   for (const prefix of prefixFallbacks[tier] ?? []) {
     const found = models.find(
-      (m) => m.provider === "openai" && m.id.startsWith(prefix) && !exactIdSet.has(m.id),
+      (m) => m.provider === "openai" && m.id.startsWith(prefix)
+        && !exactIdSet.has(m.id) && !DEPRECATED_MODELS.has(m.id),
     );
     if (found) return found;
   }
@@ -246,6 +335,60 @@ function matchLocalTier(models: RegistryModel[]): RegistryModel | undefined {
   return locals[0];
 }
 
+// ---------------------------------------------------------------------------
+// Provider-transparent tier matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a model into a tier using TIER_RULES.
+ * Returns the matching rule or undefined if no rule matches.
+ */
+export function classifyModelTier(modelId: string): { tier: Exclude<ModelTier, "local">; rule: TierRule } | undefined {
+  for (const tier of ["gloriana", "victory", "retribution"] as const) {
+    for (const rule of TIER_RULES[tier]) {
+      if (rule.exact && modelId === rule.exact) return { tier, rule };
+      if (rule.prefix && modelId.startsWith(rule.prefix)) return { tier, rule };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Match ALL viable models to a tier, across every provider.
+ * Returns candidates sorted by TIER_RULES preference order (earlier rules = preferred).
+ * Within the same rule, models are sorted by version descending (newest first).
+ */
+export function matchTierUniversal(
+  models: RegistryModel[],
+  tier: Exclude<ModelTier, "local">,
+): Array<{ model: RegistryModel; rule: TierRule }> {
+  const rules = TIER_RULES[tier];
+  const results: Array<{ model: RegistryModel; rule: TierRule; ruleIndex: number }> = [];
+
+  for (const model of models) {
+    if (model.provider === "local") continue; // local handled separately
+    if (DEPRECATED_MODELS.has(model.id)) continue;
+    for (let i = 0; i < rules.length; i++) {
+      const rule = rules[i];
+      const matches = rule.exact
+        ? model.id === rule.exact
+        : rule.prefix ? model.id.startsWith(rule.prefix) : false;
+      if (matches) {
+        results.push({ model, rule, ruleIndex: i });
+        break; // first matching rule wins for this model
+      }
+    }
+  }
+
+  // Sort: rule priority first, then newest version within same rule
+  results.sort((a, b) => {
+    if (a.ruleIndex !== b.ruleIndex) return a.ruleIndex - b.ruleIndex;
+    return compareModelVersionsDesc(a.model.id, b.model.id);
+  });
+
+  return results.map(({ model, rule }) => ({ model, rule }));
+}
+
 function dedupeProviderOrder(order: ProviderName[], avoided: ProviderName[]): ProviderName[] {
   const seen = new Set<ProviderName>();
   const result: ProviderName[] = [];
@@ -541,35 +684,48 @@ export function withCandidateCooldown(
 }
 
 export function getDefaultCapabilityProfile(models: RegistryModel[] = []): CapabilityProfile {
-  const archmagosCandidates: CapabilityCandidate[] = [];
-  const magosCandidates: CapabilityCandidate[] = [];
-  const adeptCandidates: CapabilityCandidate[] = [];
-  const servitorCandidates: CapabilityCandidate[] = [];
-  const servoskullCandidates: CapabilityCandidate[] = [];
-
-  const anthropicOpus = matchAnthropicTier(models, "gloriana");
-  const openaiOpus = matchOpenAITier(models, "gloriana");
-  const anthropicSonnet = matchAnthropicTier(models, "victory");
-  const openaiSonnet = matchOpenAITier(models, "victory");
-  const anthropicHaiku = matchAnthropicTier(models, "retribution");
-  const openaiHaiku = matchOpenAITier(models, "retribution");
   const local = matchLocalTier(models);
 
-  if (anthropicOpus) archmagosCandidates.push({ id: anthropicOpus.id, provider: "anthropic", source: "upstream", weight: "heavy", maxThinking: "high" });
-  if (openaiOpus) archmagosCandidates.push({ id: openaiOpus.id, provider: "openai", source: "upstream", weight: "heavy", maxThinking: "high" });
-
-  if (anthropicSonnet) magosCandidates.push({ id: anthropicSonnet.id, provider: "anthropic", source: "upstream", weight: "normal", maxThinking: "high" });
-  if (openaiSonnet) magosCandidates.push({ id: openaiSonnet.id, provider: "openai", source: "upstream", weight: "normal", maxThinking: "medium" });
+  // Build candidate lists from ALL available models using universal tier rules.
+  // Deduplicate by model ID — a model may appear from multiple providers
+  // (e.g. claude-opus-4-6 via both 'anthropic' and 'github-copilot'),
+  // but we want each unique provider+id pair as a separate candidate so the
+  // policy engine can prefer one provider over another.
+  function buildCandidates(tier: Exclude<ModelTier, "local">): CapabilityCandidate[] {
+    const matches = matchTierUniversal(models, tier);
+    const seen = new Set<string>();
+    const candidates: CapabilityCandidate[] = [];
+    for (const { model, rule } of matches) {
+      const key = `${model.provider}/${model.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      candidates.push({
+        id: model.id,
+        provider: model.provider as ProviderName,
+        source: rule.source,
+        weight: rule.weight,
+        maxThinking: rule.maxThinking,
+      });
+    }
+    return candidates;
+  }
 
-  if (openaiHaiku) adeptCandidates.push({ id: openaiHaiku.id, provider: "openai", source: "upstream", weight: "light", maxThinking: "low" });
-  if (anthropicHaiku) adeptCandidates.push({ id: anthropicHaiku.id, provider: "anthropic", source: "upstream", weight: "light", maxThinking: "low" });
+  const archmagosCandidates = buildCandidates("gloriana");
+  const magosCandidates = buildCandidates("victory");
+  const adeptCandidates = buildCandidates("retribution");
 
-  if (anthropicHaiku) servitorCandidates.push({ id: anthropicHaiku.id, provider: "anthropic", source: "upstream", weight: "light", maxThinking: "low" });
-  if (openaiHaiku) servitorCandidates.push({ id: openaiHaiku.id, provider: "openai", source: "upstream", weight: "light", maxThinking: "low" });
+  // Servitor: reuse adept candidates (cheapest cloud) + local
+  const servitorCandidates: CapabilityCandidate[] = [
+    ...adeptCandidates.map((c) => ({ ...c, maxThinking: "low" as ThinkingLevel })),
+  ];
   if (local) servitorCandidates.push({ id: local.id, provider: "local", source: "local", weight: inferWeightFromModel(local), maxThinking: "medium" });
 
+  // Servoskull: local first, then cheapest cloud
+  const servoskullCandidates: CapabilityCandidate[] = [];
   if (local) servoskullCandidates.push({ id: local.id, provider: "local", source: "local", weight: inferWeightFromModel(local), maxThinking: "off" });
-  if (openaiHaiku) servoskullCandidates.push({ id: openaiHaiku.id, provider: "openai", source: "upstream", weight: "light", maxThinking: "off" });
+  servoskullCandidates.push(
+    ...adeptCandidates.map((c) => ({ ...c, maxThinking: "off" as ThinkingLevel })),
+  );
 
   return {
     roles: {
@@ -712,9 +868,125 @@ export function getRoleDisplayLabel(role: CapabilityRole): string {
 
 export function getDefaultPolicy(): ProviderRoutingPolicy {
   return {
-    providerOrder: ["anthropic", "openai", "local"],
+    providerOrder: ["anthropic", "openai", "github-copilot", "google", "xai", "groq", "mistral", "amazon-bedrock", "azure-openai-responses", "openrouter", "local"],
     avoidProviders: [],
     cheapCloudPreferredOverLocal: false,
     requirePreflightForLargeRuns: true,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Provider summary — startup diagnostics
+// ---------------------------------------------------------------------------
+
+export type TierStatus = "operational" | "degraded" | "unavailable";
+
+export interface TierSummary {
+  tier: Exclude<ModelTier, "local">;
+  role: CapabilityRole;
+  status: TierStatus;
+  /** Best candidate for this tier, if any */
+  topCandidate?: { provider: string; modelId: string };
+  /** Total number of candidates across all providers */
+  candidateCount: number;
+}
+
+export interface ProviderSummary {
+  /** Providers with auth configured */
+  authProviders: string[];
+  /** Providers found in registry but no auth */
+  unauthProviders: string[];
+  /** Per-tier operational status */
+  tiers: TierSummary[];
+  /** Human-readable one-liner */
+  headline: string;
+  /** Degradation level (0=nothing, 1=local-only, 2=partial-cloud, 3=full) */
+  level: number;
+}
+
+/**
+ * Build a startup provider summary showing which tiers are operational,
+ * degraded, or unavailable based on current auth and model availability.
+ *
+ * @param allModels - ALL models from registry (getAll), used to identify unauth'd providers
+ * @param viableModels - Auth'd + non-deprecated models (getViableModels output)
+ * @param policy - Routing policy for provider ordering
+ */
+export function buildProviderSummary(
+  allModels: RegistryModel[],
+  viableModels: RegistryModel[],
+  policy: ProviderRoutingPolicy = getDefaultPolicy(),
+): ProviderSummary {
+  // Identify auth'd vs unauth'd providers
+  const allProviders = new Set(allModels.map((m) => m.provider));
+  const viableProviders = new Set(viableModels.map((m) => m.provider));
+  const authProviders = [...viableProviders].filter((p) => p !== "local").sort();
+  const unauthProviders = [...allProviders].filter((p) => !viableProviders.has(p) && p !== "local").sort();
+
+  // Build per-tier status
+  const tierDefs: Array<{ tier: Exclude<ModelTier, "local">; role: CapabilityRole }> = [
+    { tier: "gloriana", role: "archmagos" },
+    { tier: "victory", role: "magos" },
+    { tier: "retribution", role: "adept" },
+  ];
+
+  const tiers: TierSummary[] = tierDefs.map(({ tier, role }) => {
+    const candidates = matchTierUniversal(viableModels, tier);
+    const profile = getDefaultCapabilityProfile(viableModels);
+    const resolution = resolveCapabilityRole(role, viableModels, policy, profile);
+
+    let status: TierStatus;
+    let topCandidate: TierSummary["topCandidate"];
+
+    if (resolution.ok && resolution.selected) {
+      status = "operational";
+      topCandidate = {
+        provider: resolution.selected.candidate.provider,
+        modelId: resolution.selected.candidate.id,
+      };
+    } else if (candidates.length > 0) {
+      // Candidates exist but blocked by policy
+      status = "degraded";
+      topCandidate = {
+        provider: candidates[0].model.provider,
+        modelId: candidates[0].model.id,
+      };
+    } else {
+      status = "unavailable";
+    }
+
+    return { tier, role, status, topCandidate, candidateCount: candidates.length };
+  });
+
+  // Determine overall level
+  const operational = tiers.filter((t) => t.status === "operational").length;
+  const hasLocal = viableModels.some((m) => m.provider === "local");
+  let level: number;
+  if (authProviders.length === 0 && !hasLocal) {
+    level = 0;
+  } else if (authProviders.length === 0 && hasLocal) {
+    level = 1;
+  } else if (operational < 3) {
+    level = 2;
+  } else {
+    level = 3;
+  }
+
+  // Build headline
+  let headline: string;
+  if (level === 0) {
+    headline = "No providers configured. Run /bootstrap to set up API keys.";
+  } else if (level === 1) {
+    headline = "Local inference only — no cloud providers configured.";
+  } else {
+    const opTiers = tiers.filter((t) => t.status === "operational").map((t) => ROLE_DISPLAY_LABELS[t.role]);
+    const unavail = tiers.filter((t) => t.status === "unavailable").map((t) => ROLE_DISPLAY_LABELS[t.role]);
+    if (unavail.length === 0) {
+      headline = `All tiers operational via ${authProviders.join(", ")}.`;
+    } else {
+      headline = `${opTiers.join(", ")} operational. ${unavail.join(", ")} unavailable.`;
+    }
+  }
+
+  return { authProviders, unauthProviders, tiers, headline, level };
+}

package/extensions/lib/operator-fallback.ts

@@ -1,4 +1,4 @@
-import type { Model } from "@cwilson613/pi-ai";
+import type { Model } from "@styrene-lab/pi-ai";
 import {
   classifyUpstreamFailure,
   resolveCapabilityRole,

package/extensions/lib/operator-profile.ts

@@ -88,8 +88,8 @@ const DEFAULT_PROFILE: OperatorCapabilityProfile = {
       { id: "gpt-5.1-codex", provider: "openai", source: "upstream", weight: "light", maxThinking: "low" },
     ],
     servitor: [
-      { id: "gpt-4o-mini", provider: "openai", source: "upstream", weight: "light", maxThinking: "minimal" },
       { id: "claude-haiku-3-5", provider: "anthropic", source: "upstream", weight: "light", maxThinking: "minimal" },
+      { id: "gpt-5.1-codex", provider: "openai", source: "upstream", weight: "light", maxThinking: "minimal" },
     ],
     servoskull: [
       { id: "qwen3:8b", provider: "local", source: "local", weight: "light", maxThinking: "off" },

package/extensions/lib/provider-env.ts

@@ -0,0 +1,163 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// @secret ANTHROPIC_API_KEY "Anthropic API key for Claude models"
+// @secret ANTHROPIC_OAUTH_TOKEN "Anthropic OAuth token (takes precedence over API key)"
+// @secret OPENAI_API_KEY "OpenAI API key for GPT models"
+// @secret COPILOT_GITHUB_TOKEN "GitHub Copilot token (primary, set by Copilot extension)"
+// @secret GH_TOKEN "GitHub CLI token (also used as Copilot fallback)"
+// @secret GEMINI_API_KEY "Google Gemini API key"
+// @secret XAI_API_KEY "xAI API key for Grok models"
+// @secret GROQ_API_KEY "Groq API key for fast inference"
+// @secret MISTRAL_API_KEY "Mistral API key for Mistral/Codestral models"
+// @secret OPENROUTER_API_KEY "OpenRouter API key for multi-provider routing"
+// @secret AZURE_OPENAI_API_KEY "Azure OpenAI API key"
+// @secret CEREBRAS_API_KEY "Cerebras API key for fast inference"
+// @secret HF_TOKEN "HuggingFace token for gated model access"
+
+/**
+ * Mapping from pi model provider names to their env var API keys.
+ *
+ * Covers common providers from pi-ai's env-api-keys.js. Niche providers
+ * (vercel-ai-gateway, zai, minimax, opencode, kimi-coding) are omitted —
+ * add them here if they gain routing relevance.
+ *
+ * SYNC CHECK: compare against vendor/pi-mono/packages/ai/dist/env-api-keys.js
+ * when updating.
+ */
+export interface ProviderEnvEntry {
+  /** Primary env var name (the one users should configure) */
+  envVar: string;
+  /** All env vars checked by pi (in priority order) */
+  allEnvVars: string[];
+  /** Human-readable description */
+  description: string;
+}
+
+export const PROVIDER_ENV_VARS: Record<string, ProviderEnvEntry> = {
+  anthropic: {
+    // envVar is ANTHROPIC_API_KEY (what users should configure via /secrets),
+    // but allEnvVars lists ANTHROPIC_OAUTH_TOKEN first because pi checks it
+    // with higher priority at runtime (OAuth login takes precedence over key).
+    envVar: "ANTHROPIC_API_KEY",
+    allEnvVars: ["ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
+    description: "Claude models (opus, sonnet, haiku)",
+  },
+  openai: {
+    envVar: "OPENAI_API_KEY",
+    allEnvVars: ["OPENAI_API_KEY"],
+    description: "GPT models",
+  },
+  "github-copilot": {
+    envVar: "COPILOT_GITHUB_TOKEN",
+    allEnvVars: ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
+    description: "GitHub Copilot (Claude, GPT, Gemini, Grok via OAuth)",
+  },
+  google: {
+    envVar: "GEMINI_API_KEY",
+    allEnvVars: ["GEMINI_API_KEY"],
+    description: "Google Gemini models",
+  },
+  "google-vertex": {
+    // ADC auth requires credentials file + project + location (all three).
+    // GOOGLE_CLOUD_API_KEY is the simple path; ADC is complex — see
+    // isProviderEnvConfigured() special case below.
+    envVar: "GOOGLE_CLOUD_API_KEY",
+    allEnvVars: ["GOOGLE_CLOUD_API_KEY"],
+    description: "Google Vertex AI (or gcloud ADC credentials)",
+  },
+  xai: {
+    envVar: "XAI_API_KEY",
+    allEnvVars: ["XAI_API_KEY"],
+    description: "xAI Grok models",
+  },
+  groq: {
+    envVar: "GROQ_API_KEY",
+    allEnvVars: ["GROQ_API_KEY"],
+    description: "Groq fast inference",
+  },
+  mistral: {
+    envVar: "MISTRAL_API_KEY",
+    allEnvVars: ["MISTRAL_API_KEY"],
+    description: "Mistral / Codestral",
+  },
+  openrouter: {
+    envVar: "OPENROUTER_API_KEY",
+    allEnvVars: ["OPENROUTER_API_KEY"],
+    description: "OpenRouter multi-provider gateway",
+  },
+  "azure-openai-responses": {
+    envVar: "AZURE_OPENAI_API_KEY",
+    allEnvVars: ["AZURE_OPENAI_API_KEY"],
+    description: "Azure OpenAI",
+  },
+  "amazon-bedrock": {
+    envVar: "AWS_PROFILE",
+    allEnvVars: ["AWS_PROFILE", "AWS_ACCESS_KEY_ID", "AWS_BEARER_TOKEN_BEDROCK", "AWS_WEB_IDENTITY_TOKEN_FILE"],
+    description: "AWS Bedrock (profile, IAM keys, bearer token, or IRSA)",
+  },
+  cerebras: {
+    envVar: "CEREBRAS_API_KEY",
+    allEnvVars: ["CEREBRAS_API_KEY"],
+    description: "Cerebras fast inference",
+  },
+  huggingface: {
+    envVar: "HF_TOKEN",
+    allEnvVars: ["HF_TOKEN"],
+    description: "HuggingFace gated model access",
+  },
+};
+
+/**
+ * Get remediation hint for an unconfigured provider.
+ * Returns actionable text with the most appropriate fix path.
+ */
+export function getProviderRemediationHint(provider: string): string | undefined {
+  const entry = PROVIDER_ENV_VARS[provider];
+  if (!entry) return undefined;
+
+  // Providers with CLI/OAuth auth paths get special handling
+  switch (provider) {
+    case "github-copilot":
+      return "Run `/login github`, or set via `/secrets configure COPILOT_GITHUB_TOKEN`";
+    case "amazon-bedrock":
+      return "Run `aws sso login --profile <profile>` or `/secrets configure AWS_PROFILE`";
+    case "google-vertex":
+      return "Run `gcloud auth application-default login` or `/secrets configure GOOGLE_CLOUD_API_KEY`";
+    case "anthropic":
+      return "`/secrets configure ANTHROPIC_API_KEY` (or ANTHROPIC_OAUTH_TOKEN for OAuth)";
+    default:
+      return `\`/secrets configure ${entry.envVar}\``;
+  }
+}
+
+/**
+ * Check if a provider has any of its env vars set in process.env.
+ * Useful for quick auth detection without going through pi's registry.
+ */
+export function isProviderEnvConfigured(provider: string): boolean {
+  const entry = PROVIDER_ENV_VARS[provider];
+  if (!entry) return false;
+
+  // google-vertex ADC requires credentials + project + location (conjunction).
+  // Credentials can come from GOOGLE_APPLICATION_CREDENTIALS env var OR from the
+  // default ADC path (~/.config/gcloud/application_default_credentials.json) written
+  // by `gcloud auth application-default login`. Matches pi-ai's hasVertexAdcCredentials().
+  if (provider === "google-vertex") {
+    if (process.env.GOOGLE_CLOUD_API_KEY) return true;
+    const hasAdcEnv = !!(process.env.GOOGLE_APPLICATION_CREDENTIALS);
+    let hasAdcFile = false;
+    if (!hasAdcEnv) {
+      try {
+        hasAdcFile = existsSync(join(homedir(), ".config", "gcloud", "application_default_credentials.json"));
+      } catch {}
+    }
+    const hasAdc = hasAdcEnv || hasAdcFile;
+    const hasProject = !!(process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT);
+    const hasLocation = !!(process.env.GOOGLE_CLOUD_LOCATION);
+    return hasAdc && hasProject && hasLocation;
+  }
+
+  return entry.allEnvVars.some(v => !!process.env[v]);
+}