Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

32.3 KB
Raw Blame
/**
 * AI settings façade for the unified Settings → AI panel.
 *
 * Sits between the panel's React state and the Rust JSON-RPC core. Three
 * orthogonal surfaces in one place:
 *
 *  1. Cloud providers + per-workload routing → `openhuman.inference_update_model_settings`
 *  2. API keys for cloud providers           → `openhuman.auth_*_provider_credentials`
 *                                              (encrypted at rest in
 *                                              `auth-profiles.json`)
 *  3. Local provider (Ollama) status + models → existing `localAi.ts` exports
 *                                              (re-exported here for symmetry)
 *
 * The panel itself never imports `coreRpcClient` directly — every call goes
 * through this file. Keeps the wiring testable and the panel focused on
 * presentation.
 */
import { callCoreRpc } from '../../services/coreRpcClient';
import {
  authListProviderCredentials,
  type AuthProfileSummary,
  authRemoveProviderCredentials,
  authStoreProviderCredentials,
} from '../../utils/tauriCommands/auth';
import {
  type ClientConfig,
  type CloudProviderCreds,
  type ModelRegistryEntry,
  type ModelSettingsUpdate,
  openhumanGetClientConfig,
  openhumanUpdateModelSettings,
} from '../../utils/tauriCommands/config';
import {
  type InstalledModelInfo,
  type LocalAiDiagnostics,
  type LocalAiStatus,
  openhumanLocalAiDiagnostics,
  openhumanLocalAiStatus,
} from '../../utils/tauriCommands/localAi';

// ─── Domain types — what the AIPanel consumes ──────────────────────────────

export type WorkloadId = 'chat' | 'reasoning' | 'agentic' | 'coding' | 'vision' | 'memory';

export const CHAT_WORKLOADS: WorkloadId[] = ['chat', 'reasoning', 'agentic', 'coding'];
const BACKGROUND_WORKLOADS: WorkloadId[] = ['memory'];
export const ALL_WORKLOADS: WorkloadId[] = [...CHAT_WORKLOADS, ...BACKGROUND_WORKLOADS];

// Workloads that own a `<id>_provider` config field and must round-trip through
// settings serialization. Includes the tier-specific `vision` workload, which
// is deliberately NOT part of `CHAT_WORKLOADS`/`ALL_WORKLOADS`: it defaults to
// the managed vision route and is a delegate (like agentic BYOK), so it does
// not participate in the billing-suppression / "routed away from OpenHuman"
// checks in `useUsageState`.
const ROUTABLE_WORKLOADS: WorkloadId[] = [...ALL_WORKLOADS, 'vision'];
export const OPENAI_CODEX_OAUTH_MISSING_AUTH_URL = 'OPENAI_CODEX_OAUTH_MISSING_AUTH_URL';
export const OPENAI_CODEX_OAUTH_MISSING_CALLBACK_URL = 'OPENAI_CODEX_OAUTH_MISSING_CALLBACK_URL';

/** Provider reference parsed from a stored provider-string.
 *
 * Wire grammar: `"<slug>:<model>[@<temperature>]"`. The optional
 * `@<temperature>` suffix overrides the global default for this workload
 * only. The Rust factory strips it before sending the model id upstream.
 */
export type ProviderRef =
  | { kind: 'openhuman' }
  | { kind: 'default' }
  | { kind: 'cloud'; providerSlug: string; model: string; temperature?: number | null }
  | { kind: 'local'; model: string; temperature?: number | null }
  | { kind: 'claude-code'; model: string; temperature?: number | null };

/** Parse a `<model>[@<temp>]` suffix into `(model, temperature)`. */
function splitModelAndTemp(raw: string): { model: string; temperature: number | null } {
  const at = raw.lastIndexOf('@');
  if (at < 0) return { model: raw.trim(), temperature: null };
  const head = raw.slice(0, at).trim();
  const tail = raw.slice(at + 1).trim();
  const parsed = Number(tail);
  if (!head || !Number.isFinite(parsed)) {
    // Malformed suffix — treat the whole thing as the model id.
    return { model: raw.trim(), temperature: null };
  }
  return { model: head, temperature: parsed };
}

/** Format the model + optional temperature suffix used on the wire. */
function joinModelAndTemp(model: string, temperature: number | null | undefined): string {
  if (temperature == null || !Number.isFinite(temperature)) return model;
  // Two decimal places is plenty for the 0..2 slider and avoids 0.7000000001 drift.
  const rounded = Math.round(temperature * 100) / 100;
  return `${model}@${String(rounded)}`;
}

/**
 * Cloud provider entry as the UI sees it — endpoint config plus a derived
 * `has_api_key` flag (true when a key is stored in `auth-profiles.json`).
 */
export interface CloudProviderView extends CloudProviderCreds {
  has_api_key: boolean;
}

/** Model descriptor returned by providers_list_models. */
export interface ModelInfo {
  id: string;
  owned_by?: string | null;
  context_window?: number | null;
  /** Human-readable name; only the managed catalog listing supplies one. */
  display_name?: string | null;
  /** Charged price in USD per 1M tokens, when the listing publishes it. */
  input_per_1m?: number | null;
  output_per_1m?: number | null;
}

interface ProviderModelTestResult {
  reply: string;
}

interface OpenAiCodexOAuthStartResult {
  authUrl: string;
  state?: string;
  redirectUri?: string;
}

const PROVIDER_MODEL_TEST_TIMEOUT_MS = 120_000;

/** Single in-memory snapshot the AI panel renders against. */
export interface AISettings {
  cloudProviders: CloudProviderView[];
  routing: Record<WorkloadId, ProviderRef>;
  /**
   * Per-model registry carrying each model's user-set `vision` flag, keyed by
   * `(provider slug, model id)`. Surfaced in the custom-model dialog; gates chat
   * image attachments for custom/BYOK models.
   */
  modelRegistry: ModelRegistryEntry[];
  /**
   * The managed "default model" (Routing → Default model): the catalog id a
   * managed `chat` turn runs on. Raw `config.default_model` — a managed tier
   * name (`chat-v1`) or empty means nothing is pinned and the managed default runs.
   */
  defaultModel?: string;
  /**
   * #3767: authoritative, core-side per-tier decision (mirrors the Rust factory's
   * real routing resolution). For each chat-mode tier (`chat` = Quick mode,
   * `reasoning` = Reasoning mode), true when that tier runs on a non-managed
   * provider the user funds themselves (a usable BYO key, local runtime, or
   * claude-code). `useUsageState` checks the tier matching the selected mode so
   * the "buy credits" prompt is hidden exactly when the core says that mode does
   * not bill managed credits. Each entry is `false` when the core snapshot
   * predates this field (conservative — keep gating).
   *
   * Optional: `loadAISettings` always populates it, but AIPanel reconstructs a
   * draft `AISettings` for `saveAISettings` (which ignores this read-only field)
   * and test fixtures may omit it — consumers treat a missing entry as `false`.
   */
  creditsBypass?: { chat: boolean; reasoning: boolean };
}

/** Re-export so callers (e.g. the AI panel) can reference the entry type. */
export type { ModelRegistryEntry };

/** Find a model's vision flag in the registry, matching by (provider, id).
 *  Tolerates an undefined registry (older snapshots / transient load state). */
export function modelRegistryVision(
  registry: ModelRegistryEntry[] | undefined,
  provider: string,
  id: string
): boolean {
  return (registry ?? []).some(e => e.provider === provider && e.id === id && e.vision);
}

/**
 * Upsert a model's vision flag, returning a new array. Matches by
 * `(provider, id)`; a `vision: false` entry is removed (absence ⇒ no vision).
 */
export function upsertModelRegistryVision(
  registry: ModelRegistryEntry[] | undefined,
  provider: string,
  id: string,
  vision: boolean
): ModelRegistryEntry[] {
  const base = registry ?? [];
  const without = base.filter(e => !(e.provider === provider && e.id === id));
  if (!vision) {
    return without;
  }
  const existing = base.find(e => e.provider === provider && e.id === id);
  return [
    ...without,
    {
      id,
      provider,
      cost_per_1m_input: existing?.cost_per_1m_input ?? 0,
      cost_per_1m_cached_input: existing?.cost_per_1m_cached_input ?? 0,
      cost_per_1m_output: existing?.cost_per_1m_output ?? 0,
      context_window: existing?.context_window ?? 0,
      vision: true,
    },
  ];
}

// ─── Read path: load + parse ───────────────────────────────────────────────

/**
 * Parse a stored provider string (e.g. `"openai:gpt-4o"`) into a structured
 * ProviderRef. Empty/null/`"cloud"` → openhuman. Mirrors the Rust factory grammar.
 *
 * New grammar: `"<slug>:<model>"`. Legacy bare sentinels:
 *   - `"openhuman"` → { kind: 'openhuman' }
 *   - `"cloud"` or empty → { kind: 'openhuman' }
 *   - `"ollama:<model>"` → { kind: 'local', model }
 *   - `"<slug>:<model>"` → { kind: 'cloud', providerSlug: slug, model }
 */
export function parseProviderString(s: string | null | undefined): ProviderRef {
  const trimmed = (s ?? '').trim();
  if (!trimmed || trimmed === 'cloud') {
    return { kind: 'default' };
  }
  if (trimmed === 'openhuman') {
    return { kind: 'openhuman' };
  }
  if (trimmed.startsWith('ollama:')) {
    const { model, temperature } = splitModelAndTemp(trimmed.slice('ollama:'.length));
    return temperature == null ? { kind: 'local', model } : { kind: 'local', model, temperature };
  }
  if (trimmed.startsWith('claude-code:')) {
    const { model, temperature } = splitModelAndTemp(trimmed.slice('claude-code:'.length));
    return temperature == null
      ? { kind: 'claude-code', model }
      : { kind: 'claude-code', model, temperature };
  }
  const colonIdx = trimmed.indexOf(':');
  if (colonIdx > 0) {
    const slug = trimmed.slice(0, colonIdx).trim();
    const { model, temperature } = splitModelAndTemp(trimmed.slice(colonIdx + 1));
    if (slug === 'openhuman') {
      return { kind: 'openhuman' };
    }
    return temperature == null
      ? { kind: 'cloud', providerSlug: slug, model }
      : { kind: 'cloud', providerSlug: slug, model, temperature };
  }
  // Unrecognised bare string → fall back to openhuman.
  return { kind: 'openhuman' };
}

/** Serialise a `ProviderRef` back to the wire-format string. */
export function serializeProviderRef(ref: ProviderRef): string {
  switch (ref.kind) {
    case 'openhuman':
      return 'openhuman';
    case 'default':
      return 'cloud';
    case 'cloud':
      return `${ref.providerSlug}:${joinModelAndTemp(ref.model, ref.temperature)}`;
    case 'local':
      return `ollama:${joinModelAndTemp(ref.model, ref.temperature)}`;
    case 'claude-code':
      return `claude-code:${joinModelAndTemp(ref.model, ref.temperature)}`;
  }
}

/**
 * Auth-profile key for a slug-keyed provider (matches Rust `auth_key_for_slug`).
 * Used to look up whether an API key is stored for a given provider.
 */
function authKeyForSlug(slug: string): string {
  return `provider:${slug}`;
}

/**
 * Loads the full AI settings view by joining:
 *  - the core's client-config snapshot (cloud_providers + *_provider fields)
 *  - the auth profiles list (to derive `has_api_key` per cloud provider)
 *
 * Defensive: a failed `auth_list` (e.g. brand-new workspace, no profiles
 * file yet) silently degrades to `has_api_key: false` for all entries so
 * the panel still renders.
 */
export async function loadAISettings(): Promise<AISettings> {
  const [configRes, profilesRes] = await Promise.all([
    openhumanGetClientConfig(),
    authListProviderCredentials().catch((): { result: AuthProfileSummary[] } => ({ result: [] })),
  ]);
  const config: ClientConfig = configRes.result;
  // Build a set of stored provider keys for has_api_key derivation.
  // Supports both new-style `provider:<slug>` and legacy bare `<slug>`.
  const profileProviders = new Set(
    profilesRes.result.map((p: AuthProfileSummary) => p.provider.toLowerCase())
  );

  const cloudProviders: CloudProviderView[] = config.cloud_providers
    .filter(p => !['', 'cloud', 'openhuman', 'pid'].includes(p.slug.trim()))
    .map(p => {
      const newKey = authKeyForSlug(p.slug).toLowerCase();
      const legacyKey = p.slug.toLowerCase();
      const has_api_key = profileProviders.has(newKey) || profileProviders.has(legacyKey);
      return { ...p, has_api_key };
    });

  const routing: Record<WorkloadId, ProviderRef> = {
    chat: parseProviderString(config.chat_provider),
    reasoning: parseProviderString(config.reasoning_provider),
    agentic: parseProviderString(config.agentic_provider),
    coding: parseProviderString(config.coding_provider),
    vision: parseProviderString(config.vision_provider),
    memory: parseProviderString(config.memory_provider),
  };

  // Diagnostic: detect partial BYOK routing — some workloads have a BYOK cloud
  // provider configured while others are left at default/openhuman. Each route
  // is independent (#6109): an unset workload does NOT pick up a sibling's BYOK
  // provider. It resolves through `primary_cloud` instead — usually the managed
  // backend, though a legacy external `inference_url` still takes precedence
  // there, so this deliberately does not claim where it lands. This log makes
  // the split state easy to trace from the frontend side, which is the common
  // source of "why is this workload not using my key?".
  const byokProvider = (['chat', 'reasoning', 'agentic', 'coding'] as const).find(w => {
    const ref_ = routing[w];
    return ref_.kind === 'cloud';
  });
  const hasUnsetChatWorkloads = (['chat', 'reasoning', 'coding'] as const).some(w => {
    const ref_ = routing[w];
    return ref_.kind === 'default';
  });
  if (byokProvider !== undefined && hasUnsetChatWorkloads) {
    const byokSlug = (routing[byokProvider] as { kind: 'cloud'; providerSlug: string })
      .providerSlug;
    console.debug(
      '[ai-settings] partial BYOK routing detected — ' +
        byokSlug +
        ' is configured for one workload; the unset chat-tier workloads do not inherit it'
    );
  }

  // Per-model registry (vision flags). Defensive default for older snapshots.
  const modelRegistry: ModelRegistryEntry[] = config.model_registry ?? [];

  // #3767: authoritative per-tier bypass flags from the core. Each entry
  // defaults to false for older snapshots that don't carry it (conservative —
  // keep the credits gate on).
  const creditsBypass = {
    chat: config.credits_bypass?.chat === true,
    reasoning: config.credits_bypass?.reasoning === true,
  };

  const defaultModel = (config.default_model ?? '').trim();

  return { cloudProviders, routing, modelRegistry, defaultModel, creditsBypass };
}
// ─── Write path: diff + save ───────────────────────────────────────────────

/**
 * Persist a draft `AISettings` to the core. Diffs against a previous snapshot
 * and only sends fields that actually changed — keeps the patch small and
 * avoids inadvertently overwriting unrelated fields edited elsewhere.
 */
export async function saveAISettings(prev: AISettings, next: AISettings): Promise<void> {
  const patch: ModelSettingsUpdate = {};

  // Cloud providers: any change → send the full list.
  if (
    prev.cloudProviders.length !== next.cloudProviders.length ||
    prev.cloudProviders.some((p, i) => {
      const n = next.cloudProviders[i];
      return (
        !n ||
        n.id !== p.id ||
        n.slug !== p.slug ||
        n.label !== p.label ||
        n.endpoint !== p.endpoint ||
        n.ca_cert_pem !== p.ca_cert_pem ||
        n.auth_style !== p.auth_style
      );
    })
  ) {
    patch.cloud_providers = next.cloudProviders
      .filter(p => !['', 'cloud', 'openhuman', 'pid'].includes(p.slug.trim()))
      .map(({ id, slug, label, endpoint, auth_style, ca_cert_pem }) => ({
        id,
        slug,
        label,
        endpoint,
        auth_style,
        ca_cert_pem,
      }));
  }

  for (const w of ROUTABLE_WORKLOADS) {
    const a = serializeProviderRef(prev.routing[w]);
    const b = serializeProviderRef(next.routing[w]);
    if (a !== b) {
      patch[`${w}_provider` as keyof ModelSettingsUpdate] = b as never;
    }
  }

  if ((prev.defaultModel ?? '') !== (next.defaultModel ?? '')) {
    patch.default_model = next.defaultModel ?? '';
  }

  // Per-model registry (vision flags): any change → send the full list.
  if (!modelRegistriesEqual(prev.modelRegistry, next.modelRegistry)) {
    patch.model_registry = next.modelRegistry.map(
      ({
        id,
        provider,
        cost_per_1m_input,
        cost_per_1m_cached_input,
        cost_per_1m_output,
        context_window,
        vision,
      }) => ({
        id,
        provider,
        // Preserve catalog-prefilled prices + context window through the
        // round-trip; omitting them would let the Rust serde defaults zero
        // them out.
        cost_per_1m_input: cost_per_1m_input ?? 0,
        cost_per_1m_cached_input: cost_per_1m_cached_input ?? 0,
        cost_per_1m_output,
        context_window: context_window ?? 0,
        vision,
      })
    );
  }

  if (Object.keys(patch).length === 0) {
    return;
  }
  await openhumanUpdateModelSettings(patch);
}

/** Order-insensitive structural equality for two model registries. */
function modelRegistriesEqual(a: ModelRegistryEntry[], b: ModelRegistryEntry[]): boolean {
  if (a.length !== b.length) {
    return false;
  }
  const key = (e: ModelRegistryEntry) => `${e.provider} ${e.id}`;
  const bByKey = new Map(b.map(e => [key(e), e]));
  return a.every(e => {
    const m = bByKey.get(key(e));
    return (
      !!m &&
      m.vision === e.vision &&
      m.cost_per_1m_output === e.cost_per_1m_output &&
      (m.cost_per_1m_input ?? 0) === (e.cost_per_1m_input ?? 0) &&
      (m.cost_per_1m_cached_input ?? 0) === (e.cost_per_1m_cached_input ?? 0) &&
      (m.context_window ?? 0) === (e.context_window ?? 0)
    );
  });
}

// ─── API key management (per cloud provider slug) ──────────────────────────

/**
 * Store an API key for a cloud provider (encrypted at rest). Keyed by slug
 * using the new `provider:<slug>` format.
 */
export async function setCloudProviderKey(slug: string, apiKey: string): Promise<void> {
  if (slug === 'openhuman') {
    throw new Error('OpenHuman uses the session JWT — keys are not configurable here.');
  }
  // Store under both new-style key `provider:<slug>` and legacy bare `<slug>`
  // so old code paths that look up by bare slug continue to work.
  await authStoreProviderCredentials({
    provider: authKeyForSlug(slug),
    profile: 'default',
    token: apiKey,
    setActive: true,
  });
}

/**
 * Outcome of a post-save connection check (#5146 §2.4).
 *
 * `ok: false` means the credential was stored but the provider could not
 * actually serve an inference call — the "connected but unusable" state where
 * the UI previously showed a healthy provider that failed on first real use.
 */
export interface CloudProviderVerification {
  ok: boolean;
  /** Actionable, user-facing explanation. Empty when `ok`. */
  message: string;
  /** Raw provider error, kept for the details/expander. Empty when `ok`. */
  detail: string;
}

/** Minimal `{placeholder}` interpolation, matching `ProviderSetupErrorNotice`. */
function fillTemplate(template: string, replacements: Record<string, string>): string {
  return Object.entries(replacements).reduce(
    (result, [key, value]) => result.replaceAll(`{${key}}`, value),
    template
  );
}

/** Translator shape accepted here — the `(key, fallback)` form `useT` returns. */
export type TranslateFn = (key: string, fallback?: string) => string;

/**
 * Which failure a raw provider/RPC error represents (#5146 §2.4).
 *
 * Classification is kept separate from wording so the decision is unit-testable
 * without a translator and the copy can live in the locale files where the i18n
 * tooling can see it.
 */
export type ProviderVerificationReason =
  | 'auth'
  | 'model'
  | 'quota'
  | 'endpoint'
  | 'timeout'
  | 'unknown';

/** Map a raw upstream error string onto a [`ProviderVerificationReason`]. */
export function classifyProviderVerificationFailure(raw: string): ProviderVerificationReason {
  const haystack = raw.trim().toLowerCase();

  // Network / gateway / proxy rejections are about the CONNECTION, not the key.
  // They must NOT reach the `auth` branch, or the add-time flow would delete a
  // valid key over a corporate proxy, WAF, or 407 challenge (#5341) — the exact
  // failure class this change exists to preserve keys through. Checked first so
  // `authentication` in "407 Proxy Authentication Required" and a WAF/Cloudflare
  // "403 Forbidden" classify as `unknown` (non-destructive), not `auth`.
  if (
    /\b407\b/.test(haystack) ||
    haystack.includes('proxy') ||
    haystack.includes('cloudflare') ||
    haystack.includes('bad gateway') ||
    haystack.includes('gateway timeout')
  ) {
    return 'unknown';
  }

  // Rejected credential (revoked / invalid / no-permission key). A 403 counts
  // only when it co-occurs with credential wording — a bare 403 from an
  // unidentified intermediary is not proof the key itself is bad. Word
  // boundaries keep `401`/`403` from matching ids like `1403` / `4032`.
  const is403Credential =
    /\b403\b/.test(haystack) &&
    (haystack.includes('forbidden') ||
      haystack.includes('key') ||
      haystack.includes('credential') ||
      haystack.includes('permission'));
  if (
    /\b401\b/.test(haystack) ||
    is403Credential ||
    haystack.includes('invalid api key') ||
    haystack.includes('invalid_api_key') ||
    haystack.includes('incorrect api key') ||
    haystack.includes('unauthorized') ||
    haystack.includes('authentication')
  ) {
    return 'auth';
  }
  if (
    haystack.includes('model_not_found') ||
    // Must be tested here: the endpoint branch below matches a bare
    // 'not found', which would otherwise claim every provider that phrases a
    // missing model as "model not found" or "The model `x` was not found" and
    // send the user off to check their base URL instead of their model id.
    (haystack.includes('not found') && haystack.includes('model')) ||
    haystack.includes('does not exist') ||
    haystack.includes('is not available') ||
    haystack.includes('unknown model') ||
    haystack.includes('invalid model')
  ) {
    return 'model';
  }
  if (
    haystack.includes('quota') ||
    haystack.includes('insufficient') ||
    haystack.includes('billing') ||
    haystack.includes('429') ||
    haystack.includes('rate limit')
  ) {
    return 'quota';
  }
  if (haystack.includes('404') || haystack.includes('not found')) {
    return 'endpoint';
  }
  if (haystack.includes('timeout') || haystack.includes('timed out')) {
    return 'timeout';
  }
  return 'unknown';
}

/**
 * Turn a raw provider/RPC failure into something a user can act on (#5146 §2.4).
 *
 * Storing a key only proves we wrote it to disk. The failures users actually
 * hit (wrong model id, exhausted quota, a base URL that doesn't speak the
 * endpoint we call) all surface as opaque upstream strings, so map the common
 * shapes onto a concrete next step and pass anything unrecognised through
 * verbatim rather than inventing a diagnosis.
 *
 * The rendered string is user-visible UI text, so it goes through `t` like the
 * sibling `presentProviderSetupError`: the caller passes the translator from
 * `useT()` and every branch resolves against the locale files. `slug` must be
 * the bare provider slug (`openai`), not a composite `provider:model` string.
 */
export function describeProviderVerificationFailure(
  slug: string,
  raw: string,
  t: TranslateFn
): string {
  const detail = raw.trim();
  const reason = classifyProviderVerificationFailure(detail);

  switch (reason) {
    case 'auth':
      return fillTemplate(
        t(
          'settings.ai.providerTest.authRejected',
          "The key was saved, but '{slug}' rejected it. Check that you pasted the whole key and that it is still active in the provider's dashboard."
        ),
        { slug }
      );
    case 'model':
      return fillTemplate(
        t(
          'settings.ai.providerTest.modelNotRecognized',
          "The key was saved and accepted, but '{slug}' does not recognise the selected model. Pick a model id this provider actually serves (its default model is set on the provider entry)."
        ),
        { slug }
      );
    case 'quota':
      return fillTemplate(
        t(
          'settings.ai.providerTest.quotaOrBilling',
          "The key was saved and accepted, but '{slug}' refused the request for quota or billing reasons. Check your account balance and rate limits with the provider."
        ),
        { slug }
      );
    case 'endpoint':
      return fillTemplate(
        t(
          'settings.ai.providerTest.endpointNotFound',
          "The key was saved, but the configured endpoint for '{slug}' returned 404. Check the base URL: an OpenAI-compatible provider usually needs the '/v1' suffix (e.g. https://api.openai.com/v1)."
        ),
        { slug }
      );
    case 'timeout':
      return fillTemplate(
        t(
          'settings.ai.providerTest.timeout',
          "The key was saved, but '{slug}' did not respond in time. Check the endpoint URL and your network, then test again."
        ),
        { slug }
      );
    default:
      // Deliberately generic. The upstream string can echo request material
      // (headers, key fragments) and this lands in a screenshot-able banner, so
      // it must not be interpolated into user-visible copy. The raw text stays
      // on `CloudProviderVerification.detail` for the details surface and is
      // logged by the caller for local diagnosis.
      return fillTemplate(
        t(
          'settings.ai.providerTest.unknown',
          "The key was saved, but a test call to '{slug}' failed. Check the provider's status page and the endpoint URL, then test again."
        ),
        { slug }
      );
  }
}

/**
 * Prove a freshly configured provider can actually run inference (#5146 §2.4).
 *
 * Runs one real, minimal completion through the existing
 * `openhuman.inference_test_provider_model` RPC. Never throws: a provider that
 * cannot serve a request is a *result*, not an exception, because the caller
 * always wants to show it rather than lose the save.
 */
export async function verifyCloudProviderConnection(
  provider: string,
  workload: WorkloadId = 'chat',
  t: TranslateFn = (_key, fallback) => fallback ?? ''
): Promise<CloudProviderVerification> {
  // The core only builds a configured cloud provider from the `<slug>:<model>`
  // form, so a bare slug would be rejected as an unrecognised provider and a
  // perfectly good key would be reported as broken. Callers pass the same
  // composite string the Test button uses; the bare slug is what the *messages*
  // name, so derive it rather than echoing `provider:model[:temp]` at the user.
  const providerString = provider.trim();
  const slug = providerString.split(':')[0]?.trim() || providerString;

  console.debug(`[ai-settings][verify] start workload=${workload} slug=${slug}`);
  try {
    const result = await testProviderModel(workload, providerString, 'ping');
    const reply = (result?.reply ?? '').trim();
    if (!reply) {
      console.debug(`[ai-settings][verify] empty-reply workload=${workload} slug=${slug}`);
      return {
        ok: false,
        message: fillTemplate(
          t(
            'settings.ai.providerTest.emptyReply',
            "The key was saved, but '{slug}' returned an empty response to a test prompt. Check the model id configured for this provider."
          ),
          { slug }
        ),
        detail: '',
      };
    }
    console.debug(`[ai-settings][verify] ok workload=${workload} slug=${slug}`);
    return { ok: true, message: '', detail: '' };
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error);
    // The raw detail can carry provider text; log only the classification.
    console.error(
      `[ai-settings][verify] failed workload=${workload} slug=${slug} reason=${classifyProviderVerificationFailure(detail)}`
    );
    return { ok: false, message: describeProviderVerificationFailure(slug, detail, t), detail };
  }
}

/** Clear a stored API key. */
export async function clearCloudProviderKey(slug: string): Promise<void> {
  if (slug === 'openhuman') {
    return;
  }
  // Clear the new-style key. Legacy bare-slug entries are left as-is
  // since we can't be sure they aren't used by other things.
  await authRemoveProviderCredentials({ provider: authKeyForSlug(slug), profile: 'default' });
}

export async function startOpenAiCodexOAuth(): Promise<OpenAiCodexOAuthStartResult> {
  const res = await callCoreRpc<{ result: OpenAiCodexOAuthStartResult }>({
    method: 'openhuman.inference_openai_oauth_start',
    params: {},
  });
  const authUrl = res?.result?.authUrl?.trim();
  if (!authUrl) {
    throw new Error(OPENAI_CODEX_OAUTH_MISSING_AUTH_URL);
  }
  return res.result;
}

export async function completeOpenAiCodexOAuth(callbackUrl: string): Promise<void> {
  const callback = callbackUrl.trim();
  if (!callback) {
    throw new Error(OPENAI_CODEX_OAUTH_MISSING_CALLBACK_URL);
  }
  await callCoreRpc({
    method: 'openhuman.inference_openai_oauth_complete',
    params: { callback_url: callback },
  });
}

export async function importOpenAiCodexCliAuth(): Promise<void> {
  await callCoreRpc({ method: 'openhuman.inference_openai_oauth_import_codex_cli', params: {} });
}

/**
 * Eagerly write the cloud_providers list to the core config.
 *
 * Called immediately when providers are added/edited/removed so that
 * `listProviderModels` can resolve the provider by id without waiting for
 * the user to click the global Save button.  API keys are NOT included here
 * (they're written via `setCloudProviderKey` on their own path).
 */
export async function flushCloudProviders(providers: CloudProviderCreds[]): Promise<void> {
  await openhumanUpdateModelSettings({ cloud_providers: providers });
}

/**
 * Fetch the model list from a configured cloud provider's /models API.
 * `providerId` may be either the provider's opaque id or its slug — Rust
 * accepts both. Prefer passing the slug so lookup works before the provider
 * config has been persisted to disk (i.e. before the user clicks Save).
 * Throws on error so callers can surface retry UI.
 */
export async function listProviderModels(providerId: string): Promise<ModelInfo[]> {
  const res = await callCoreRpc<{ result: { models: ModelInfo[] } }>({
    method: 'openhuman.inference_list_models',
    params: { provider_id: providerId },
  });
  return res?.result?.models ?? [];
}

/**
 * A BYO provider auth failure (invalid / revoked key, 401 / 403) recorded by
 * the core this process. Mirrors the Rust `ProviderAuthError`. Backs the
 * inline provider-error notice in the AI panel so a key that breaks at runtime
 * — often in a silent background loop like memory summarization — is surfaced
 * next to the key editor, not only in the notification center.
 */
export interface ProviderAuthError {
  provider: string;
  status: number;
  message: string;
  timestamp_ms: number;
}

/** Fetch BYO provider auth failures recorded this process, keyed by slug. */
export async function loadProviderAuthErrors(): Promise<ProviderAuthError[]> {
  const res = await callCoreRpc<{ result: { errors: ProviderAuthError[] } }>({
    method: 'openhuman.inference_provider_auth_errors',
    params: {},
  });
  return res?.result?.errors ?? [];
}

export async function testProviderModel(
  workload: WorkloadId,
  provider: string,
  prompt = 'Hello world'
): Promise<ProviderModelTestResult> {
  const res = await callCoreRpc<{ result: ProviderModelTestResult }>({
    method: 'openhuman.inference_test_provider_model',
    params: { workload, provider, prompt },
    timeoutMs: PROVIDER_MODEL_TEST_TIMEOUT_MS,
  });
  if (!res?.result) {
    throw new Error(
      `Model test RPC returned no result for ${workload} via ${provider} (openhuman.inference_test_provider_model).`
    );
  }
  return res.result;
}

// ─── Local provider snapshot (user-run Ollama endpoint: detect + list) ────

/**
 * Snapshot of the user-run local endpoint (Ollama / LM Studio / any
 * OpenAI-compatible server) and its installed models for the AI panel. The app
 * never installs the runtime or downloads models — the user does that.
 */
export interface LocalProviderSnapshot {
  status: LocalAiStatus | null;
  diagnostics: LocalAiDiagnostics | null;
  installedModels: InstalledModelInfo[];
}

export async function loadLocalProviderSnapshot(): Promise<LocalProviderSnapshot> {
  const [statusRes, diag] = await Promise.all([
    openhumanLocalAiStatus().catch((): { result: LocalAiStatus | null } => ({ result: null })),
    openhumanLocalAiDiagnostics().catch((): LocalAiDiagnostics | null => null),
  ]);
  return {
    status: statusRes.result,
    diagnostics: diag,
    installedModels: diag?.installed_models ?? [],
  };
}