@bhooai/nexus-cli 2.0.5 → 2.0.7

package/templates/base/apps/admin/src/pages/ai/AiProviders.tsx

@@ -0,0 +1,276 @@
+import React, { useEffect, useState } from 'react';
+import { Icon } from '../../icons.js';
+import { SafeGotoLink } from '@bhooai/nexus-safe-goto';
+import {
+  getAiProviders, updateAiProvider, addAiProvider, deleteAiProvider, testAiProvider,
+  type AiProviderView, type AiProviderPersistence, type AiProviderTestResult,
+} from '../../api.js';
+import { useAdminAlert } from '../../alertCenter.js';
+import type { ToggleStyle, ProviderFilter } from '../../lib/types.js';
+import { BUILTIN_PROVIDER_IDS } from '../../lib/constants.js';
+import { ProviderGroup } from './ProviderGroup.js';
+import { AddProviderDialog } from './AddProviderDialog.js';
+import { ProviderKeyDialog } from './ProviderKeyDialog.js';
+
+export function AiProviders({ toggle }: { toggle: ToggleStyle }) {
+  const [providers, setProviders] = useState<AiProviderView[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [msg, setMsg] = useAdminAlert('ai-providers');
+  const [showAdd, setShowAdd] = useState(false);
+  const [newProvider, setNewProvider] = useState({ id: '', label: '', baseUrl: '', apiKey: '', defaultModel: '' });
+  const [query, setQuery] = useState('');
+  const [filter, setFilter] = useState<ProviderFilter>('enabled');
+  const [testingId, setTestingId] = useState<string | null>(null);
+  const [testResults, setTestResults] = useState<Record<string, AiProviderTestResult>>({});
+  const [keyEditorProvider, setKeyEditorProvider] = useState<AiProviderView | null>(null);
+  const [keyDraft, setKeyDraft] = useState('');
+  const [switchAnim, setSwitchAnim] = useState<Record<string, 'out' | 'in' | null>>({});
+
+  useEffect(() => { loadProviders(); }, []);
+
+  const wait = (ms: number) => new Promise<void>((resolve) => window.setTimeout(resolve, ms));
+
+  const loadProviders = async () => {
+    try { const r = await getAiProviders(); setProviders(r.providers ?? []); } catch { /* non-fatal */ }
+  };
+
+  const persistenceNote = (persistence?: AiProviderPersistence): string => {
+    if (!persistence) return '';
+    const missing = [
+      !persistence.runtime ? 'nexus.runtime.json' : '',
+      !persistence.database ? 'MongoDB' : '',
+    ].filter(Boolean);
+    return missing.length ? ` Persistence failed: ${missing.join(' and ')}.` : '';
+  };
+
+  const openKeyEditor = (provider: AiProviderView) => {
+    setKeyEditorProvider(provider);
+    setKeyDraft('');
+  };
+
+  const closeKeyEditor = () => {
+    if (busy) return;
+    setKeyEditorProvider(null);
+    setKeyDraft('');
+  };
+
+  const saveKeyFromEditor = async () => {
+    if (!keyEditorProvider || !keyDraft.trim()) return;
+    const saved = await saveApiKey(keyEditorProvider, keyDraft);
+    if (saved) {
+      setKeyEditorProvider(null);
+      setKeyDraft('');
+    }
+  };
+
+  const toggleProvider = async (p: AiProviderView) => {
+    setMsg('');
+    setBusy(true);
+    setSwitchAnim((prev) => ({ ...prev, [p.id]: 'out' }));
+    await wait(280);
+    try {
+      const result = await updateAiProvider(p.id, { enabled: !p.enabled });
+      setProviders((current) => current.map((item) => item.id === p.id ? result.provider : item));
+      setSwitchAnim((prev) => ({ ...prev, [p.id]: 'in' }));
+      setMsg(`${p.label} ${result.provider.enabled ? 'enabled' : 'disabled'}.${persistenceNote(result.persistence)}`);
+    }
+    catch (e: any) {
+      setSwitchAnim((prev) => { const next = { ...prev }; delete next[p.id]; return next; });
+      setMsg(`Failed: ${e?.message ?? e}`);
+    }
+    finally {
+      setBusy(false);
+      await wait(420);
+      setSwitchAnim((prev) => { const next = { ...prev }; delete next[p.id]; return next; });
+    }
+  };
+
+  const saveApiKey = async (p: AiProviderView, key: string): Promise<boolean> => {
+    if (!key.trim()) return false;
+    setBusy(true);
+    try {
+      const result = await updateAiProvider(p.id, { apiKey: key.trim() });
+      // Update only the provider that changed. Refreshing the whole collection
+      // here can replace the visible 20-provider list with a stale/empty read
+      // while the backend is persisting the key.
+      setProviders((current) => current.map((item) => item.id === p.id ? result.provider : item));
+      setMsg(`${p.label} API key saved.${persistenceNote(result.persistence)}`);
+      return true;
+    } catch (e: any) {
+      setMsg(`Failed: ${e?.message ?? e}`);
+      return false;
+    } finally { setBusy(false); }
+  };
+
+  const saveDefaultModel = async (p: AiProviderView, m: string) => {
+    setBusy(true);
+    try {
+      const result = await updateAiProvider(p.id, { defaultModel: m.trim() });
+      setProviders((current) => current.map((item) => item.id === p.id ? result.provider : item));
+      setMsg(`${p.label} model saved.${persistenceNote(result.persistence)}`);
+    }
+    catch (e: any) { setMsg(`Failed: ${e?.message ?? e}`); }
+    finally { setBusy(false); }
+  };
+
+  const addProvider = async () => {
+    if (!newProvider.id.trim() || !newProvider.label.trim() || !newProvider.baseUrl.trim()) { setMsg('id, label and baseUrl are required'); return; }
+    setBusy(true);
+    try {
+      const result = await addAiProvider({ id: newProvider.id.trim().toLowerCase(), label: newProvider.label.trim(), baseUrl: newProvider.baseUrl.trim(), apiKey: newProvider.apiKey.trim() || undefined, defaultModel: newProvider.defaultModel.trim() || undefined, enabled: true });
+      setProviders((current) => [...current, result.provider]);
+      setShowAdd(false);
+      setNewProvider({ id: '', label: '', baseUrl: '', apiKey: '', defaultModel: '' });
+      setMsg(`Provider added.${persistenceNote(result.persistence)}`);
+    } catch (e: any) { setMsg(`Failed: ${e?.message ?? e}`); }
+    finally { setBusy(false); }
+  };
+
+  const removeProvider = async (id: string) => {
+    setBusy(true);
+    try {
+      const result = await deleteAiProvider(id);
+      setProviders((current) => current.filter((item) => item.id !== id));
+      setTestResults((prev) => { const next = { ...prev }; delete next[id]; return next; });
+      setMsg(`Provider removed.${persistenceNote(result.persistence)}`);
+    }
+    catch (e: any) { setMsg(`Failed: ${e?.message ?? e}`); }
+    finally { setBusy(false); }
+  };
+
+  const testProvider = async (p: AiProviderView) => {
+    setTestingId(p.id);
+    setMsg('');
+    try {
+      const result = await testAiProvider(p.id);
+      setTestResults((prev) => ({ ...prev, [p.id]: result }));
+      if (result.ok) setMsg(`${p.label}: reachable — ${result.modelCount ?? 0} model(s).`);
+      else setMsg(`${p.label}: ${result.error ?? 'unreachable'}.`);
+    } catch (e: any) {
+      setTestResults((prev) => ({ ...prev, [p.id]: { ok: false, provider: p.id, error: String(e?.message ?? e), checkedAt: new Date().toISOString() } }));
+      setMsg(`${p.label}: ${e?.message ?? e}`);
+    } finally {
+      setTestingId(null);
+    }
+  };
+
+  // Search + filter logic.
+  const matchesQuery = (p: AiProviderView) => {
+    if (!query.trim()) return true;
+    const q = query.toLowerCase();
+    return p.id.toLowerCase().includes(q) || p.label.toLowerCase().includes(q);
+  };
+
+  const enabled = providers.filter((p) => matchesQuery(p) && p.enabled && BUILTIN_PROVIDER_IDS.has(p.id));
+  const disabled = providers.filter((p) => matchesQuery(p) && !p.enabled && BUILTIN_PROVIDER_IDS.has(p.id));
+  const custom = providers.filter((p) => matchesQuery(p) && !BUILTIN_PROVIDER_IDS.has(p.id));
+
+  const groups: Array<{ id: string; label: string; icon: string; items: AiProviderView[] }> = [];
+  if (filter === 'all' || filter === 'enabled') {
+    if (enabled.length) groups.push({ id: 'enabled', label: 'Enabled', icon: '●', items: enabled });
+  }
+  if (filter === 'all' || filter === 'disabled') {
+    if (disabled.length) groups.push({ id: 'disabled', label: 'Disabled', icon: 'â—‹', items: disabled });
+  }
+  if (filter === 'all' || filter === 'custom') {
+    if (custom.length) groups.push({ id: 'custom', label: 'Custom', icon: '✚', items: custom });
+  }
+
+  const filterPills: Array<[ProviderFilter, string, number]> = [
+    ['all', 'All', providers.length],
+    ['enabled', 'Enabled', enabled.length],
+    ['disabled', 'Disabled', disabled.length],
+    ['custom', 'Custom', custom.length],
+  ];
+
+  return (
+    <div className="space-y-4">
+
+      {/* Header */}
+      <section className="glass-card space-y-3">
+        <div className="flex items-center justify-between">
+          <h3 className="glass-h3">AI providers ({providers.length})</h3>
+          <div className="flex gap-2">
+            <button onClick={loadProviders} disabled={busy} className="glass-chip-btn">refresh</button>
+            <button onClick={() => setShowAdd(true)} disabled={busy} className="glass-chip-btn">+ add provider</button>
+          </div>
+        </div>
+
+        {/* Filter bar */}
+        <div className="provider-filter-bar">
+          <div className="relative flex-1 sm:w-64">
+            <span className="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-slate-500"><Icon name="search" size={13} /></span>
+            <input
+              className="glass-input !py-1.5 text-sm w-full sm:w-64 pl-8"
+              placeholder="Search providers…"
+              type="search"
+              autoComplete="off"
+              autoCapitalize="none"
+              autoCorrect="off"
+              spellCheck={false}
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+            />
+          </div>
+          <div className="flex flex-wrap gap-1.5">
+            {filterPills.map(([id, label, count]) => (
+              <button
+                key={id}
+                onClick={() => setFilter(id)}
+                className={filter === id ? 'glass-btn-primary !py-1 !px-2.5 text-xs' : 'glass-chip-btn'}
+              >
+                {label} <span className="ml-1 opacity-60">{count}</span>
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Groups */}
+        {groups.length === 0 && (
+          <p className="text-xs text-slate-500 py-4 text-center">
+            {providers.length === 0 ? 'No providers configured.' : 'No providers match your search/filter.'}
+          </p>
+        )}
+        {groups.map((g) => (
+          <ProviderGroup
+            key={g.id}
+            label={g.label}
+            icon={g.icon}
+            items={g.items}
+            toggle={toggle}
+            switchAnim={switchAnim}
+            busy={busy}
+            testingId={testingId}
+            testResults={testResults}
+            onToggle={toggleProvider}
+            onSaveModel={saveDefaultModel}
+            onRemove={removeProvider}
+            onTest={testProvider}
+            onOpenKey={openKeyEditor}
+          />
+        ))}
+      </section>
+
+      {/* Add provider modal */}
+      {showAdd && (
+        <AddProviderDialog
+          value={newProvider}
+          onChange={setNewProvider}
+          onSubmit={addProvider}
+          onCancel={() => setShowAdd(false)}
+          busy={busy}
+        />
+      )}
+      {keyEditorProvider && (
+        <ProviderKeyDialog
+          provider={keyEditorProvider}
+          value={keyDraft}
+          onChange={setKeyDraft}
+          onSave={saveKeyFromEditor}
+          onCancel={closeKeyEditor}
+          busy={busy}
+        />
+      )}
+    </div>
+  );
+}

package/templates/base/apps/admin/src/pages/ai/AiSettings.tsx

@@ -0,0 +1,84 @@
+import React, { useEffect, useState } from 'react';
+import { getAdminConfig, getAiStatus, type AdminConfig, type AiStatus } from '../../api.js';
+import { useAdminAlert } from '../../alertCenter.js';
+
+export function AiSettings() {
+  const [config, setConfig] = useState<AdminConfig | null>(null);
+  const [aiStatus, setAiStatus] = useState<AiStatus | null>(null);
+  const [aiErr, setAiErr] = useState('');
+  const [msg, setMsg] = useAdminAlert('ai-settings');
+
+  useEffect(() => {
+    getAdminConfig().then((c) => setConfig(c)).catch(() => {});
+    checkAi();
+  }, []);
+
+  const checkAi = async () => {
+    setAiErr('');
+    try { setAiStatus(await getAiStatus()); }
+    catch (e: any) { setAiErr(String(e?.message ?? e)); }
+  };
+
+  const ai = config?.config?.ai as { serverUrl: string; timeoutMs: number; defaultProvider: string; schemaModel: string } | undefined;
+
+  return (
+    <div className="space-y-4">
+
+      <section className="glass-card space-y-3">
+        <h3 className="glass-h3">AI configuration</h3>
+        {ai ? (
+          <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-4">
+            {([
+              ['Server URL', ai.serverUrl],
+              ['Timeout', `${(ai.timeoutMs / 1000).toFixed(0)}s`],
+              ['Default provider', ai.defaultProvider],
+              ['Schema model', ai.schemaModel],
+            ] as const).map(([label, value]) => (
+              <div key={label} className="glass rounded-xl px-3 py-2">
+                <span className="admin-overline">{label}</span>
+                <code className="block mt-1 truncate font-mono text-sm text-slate-200">{value}</code>
+              </div>
+            ))}
+          </div>
+        ) : (
+          <p className="text-xs text-slate-500">Loading settings…</p>
+        )}
+      </section>
+
+      <section className="glass-card space-y-3">
+        <div className="flex items-center justify-between">
+          <h3 className="glass-h3">AI server health</h3>
+          <button onClick={checkAi} className="glass-chip-btn">re-check</button>
+        </div>
+        {aiErr && <p className="text-xs text-rose-400">{aiErr}</p>}
+        <div className="grid grid-cols-1 gap-3 md:grid-cols-3">
+          {aiStatus ? (
+            <>
+              {([
+                ['AI server', aiStatus.aiServer, aiStatus.aiServer.detail ? `health: ${aiStatus.aiServer.detail.status ?? 'unknown'}` : undefined],
+                ['Ollama', aiStatus.ollama, aiStatus.ollama.detail?.modelCount != null ? `${aiStatus.ollama.detail.modelCount} model(s)` : undefined],
+              ] as const).map(([label, s, detail]) => (
+                <div key={label} className="glass flex items-center gap-2 rounded-xl px-3 py-2 text-sm">
+                  <span className={s.ok ? 'dot-ok' : 'dot-bad'} />
+                  <span className="font-medium text-slate-200">{label}</span>
+                  <span className={`text-xs ${s.ok ? 'text-emerald-400' : 'text-rose-400'}`}>{s.ok ? (detail ?? 'ok') : (s.error ?? 'down')}</span>
+                </div>
+              ))}
+            </>
+          ) : (
+            <p className="col-span-3 text-xs text-slate-500">No status yet{aiErr ? '' : ' — run a check'}.</p>
+          )}
+        </div>
+        {aiStatus && <p className="text-xs text-slate-500">"auto" currently resolves to <span className="font-mono text-slate-300">{aiStatus.autoResolvesTo}</span> on the AI server.</p>}
+        {aiStatus?.aiServer?.detail?.providers && (
+          <div className="flex flex-wrap gap-2">
+            <span className="text-xs text-slate-500">Available providers on AI server:</span>
+            {aiStatus.aiServer.detail.providers.map((p) => (
+              <span key={p} className="glass-chip text-xs">{p}</span>
+            ))}
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}

package/templates/base/apps/admin/src/pages/ai/ProviderCard.tsx

@@ -0,0 +1,145 @@
+import React, { useState } from 'react';
+import { Icon, isIconName } from '../../icons.js';
+import { SafeGotoLink } from '@bhooai/nexus-safe-goto';
+import type { ToggleStyle } from '../../lib/types.js';
+import { PRESET_BY_ID } from '../../lib/constants.js';
+import { providerMeta, isLocalProvider, websiteFromBaseUrl } from '../../lib/utils.js';
+import type { AiProviderView, AiProviderTestResult } from '../../api.js';
+
+export function ProviderCard({ provider, toggle, anim, busy, isCustom, testing, testResult, onToggle, onSaveModel, onRemove, onTest, onOpenKey }: {
+  provider: AiProviderView;
+  toggle: ToggleStyle;
+  anim: 'out' | 'in' | null;
+  busy: boolean;
+  isCustom: boolean;
+  testing: boolean;
+  testResult?: AiProviderTestResult;
+  onToggle: () => void;
+  onSaveModel: (model: string) => void;
+  onRemove: () => void;
+  onTest: () => void;
+  onOpenKey: () => void;
+}) {
+  const [editingModel, setEditingModel] = useState(false);
+  const [modelInput, setModelInput] = useState(provider.defaultModel ?? '');
+
+  const meta = providerMeta(provider.id);
+  const local = isLocalProvider(provider.baseUrl);
+  const cardClass = provider.enabled
+    ? provider.hasApiKey ? 'is-on' : 'is-warn'
+    : 'is-off';
+
+  return (
+    <div className={`provider-card ${cardClass}${anim === 'out' ? ' is-switch-out' : ''}${anim === 'in' ? ' is-switch-in' : ''}`} style={{ ['--avatar-hue' as string]: String(meta.hue) }}>
+      {/* Header: avatar + label/id + toggle */}
+      <div className="flex items-center gap-2.5">
+        <span className="provider-avatar" style={{ ['--avatar-hue' as string]: String(meta.hue) }}>{isIconName(meta.glyph) ? <Icon name={meta.glyph} size={16} /> : meta.glyph}</span>
+        <div className="flex-1 min-w-0">
+          <div className="font-medium text-sm text-slate-200 truncate">{provider.label}</div>
+          <div className="text-[11px] text-slate-500 font-mono truncate">{provider.id}</div>
+        </div>
+        <button
+          type="button"
+          onClick={onToggle}
+          disabled={busy}
+          className={`ai-toggle tg-${toggle} ${provider.enabled ? 'is-on' : ''}`}
+          title={provider.enabled ? 'Enabled — click to disable' : 'Disabled — click to enable'}
+        >
+          <span className="ai-toggle-knob" />
+        </button>
+      </div>
+
+      {/* Status badges */}
+      <div className="flex flex-wrap items-center gap-1.5">
+        {provider.hasApiKey
+          ? <span className="provider-badge-ok">✓ key</span>
+          : <span className="provider-badge-warn">no key</span>}
+        {provider.enabled
+          ? <span className="provider-badge-ok">enabled</span>
+          : <span className="provider-badge-mute">disabled</span>}
+        {isCustom && <span className="provider-badge-accent">custom</span>}
+        {local && <span className="provider-badge-local">local</span>}
+      </div>
+
+      {/* Model row */}
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <span className="text-[11px] text-slate-500 shrink-0">Model</span>
+          {editingModel ? (
+            <>
+              <input
+                className="glass-input !py-1 text-xs font-mono flex-1"
+                placeholder="default model"
+                value={modelInput}
+                onChange={(e) => setModelInput(e.target.value)}
+                autoFocus
+              />
+              <button
+                type="button"
+                onClick={() => { onSaveModel(modelInput); setEditingModel(false); }}
+                disabled={busy || !modelInput.trim()}
+                className="glass-chip-btn shrink-0 text-[10px]"
+              >save</button>
+              <button
+                type="button"
+                onClick={() => { setEditingModel(false); setModelInput(provider.defaultModel ?? ''); }}
+                className="glass-chip-btn shrink-0 text-[10px]"
+              >cancel</button>
+            </>
+          ) : (
+            <>
+              <code className="text-xs text-slate-300 font-mono truncate flex-1">{provider.defaultModel || '—'}</code>
+              <button type="button" onClick={() => setEditingModel(true)} disabled={busy} className="glass-chip-btn shrink-0 text-[10px]" title="Edit model"><Icon name="pencil" size={11} /></button>
+            </>
+          )}
+        </div>
+        {editingModel && PRESET_BY_ID[provider.id]?.models?.length ? (
+          <select
+            className="glass-input !py-1 text-xs font-mono"
+            value=""
+            onChange={(e) => { if (e.target.value) setModelInput(e.target.value); }}
+          >
+            <option value="" className="bg-slate-900">…or pick a popular model</option>
+            {PRESET_BY_ID[provider.id]!.models.map((m) => (
+              <option key={m} value={m} className="bg-slate-900">{m}</option>
+            ))}
+          </select>
+        ) : null}
+      </div>
+
+      {/* Footer: baseUrl + website + set key */}
+      <div className="flex flex-wrap items-center gap-1.5">
+        <code className="text-[10px] text-slate-500 truncate flex-1 min-w-[100px]">{provider.baseUrl}</code>
+        <SafeGotoLink href={websiteFromBaseUrl(provider.baseUrl)} className="glass-chip-btn shrink-0 text-[10px]"><Icon name="externalLink" size={11} /></SafeGotoLink>
+        <button
+          type="button"
+          onClick={onOpenKey}
+          disabled={busy}
+          className="glass-chip-btn shrink-0 text-[10px]"
+        >key</button>
+        {isCustom && (
+          <button type="button" onClick={onRemove} disabled={busy} className="glass-chip-btn-danger shrink-0 text-[10px]" title="Remove provider"><Icon name="trash" size={11} /></button>
+        )}
+      </div>
+
+      {/* Test row */}
+      <div className="flex items-center gap-2 pt-0.5 border-t border-white/[0.06]">
+        <button type="button" onClick={onTest} disabled={busy || testing} className="glass-chip-btn shrink-0 text-[10px]">
+          {testing ? 'testing…' : <><Icon name="zap" size={11} /> test</>}
+        </button>
+        {testResult && (
+          testResult.ok ? (
+            <span className="text-[10px] text-emerald-300 truncate">
+              ✓ {testResult.modelCount ?? 0} model{testResult.modelCount === 1 ? '' : 's'}
+              {testResult.models && testResult.models.length > 0 && (
+                <span className="text-slate-500"> — {testResult.models.slice(0, 3).join(', ')}{testResult.models.length > 3 ? '…' : ''}</span>
+              )}
+            </span>
+          ) : (
+            <span className="text-[10px] text-rose-400 truncate" title={testResult.error}>✗ {testResult.error ?? 'unreachable'}</span>
+          )
+        )}
+      </div>
+    </div>
+  );
+}

package/templates/base/apps/admin/src/pages/ai/ProviderGroup.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import type { ToggleStyle } from '../../lib/types.js';
+import { BUILTIN_PROVIDER_IDS } from '../../lib/constants.js';
+import type { AiProviderView, AiProviderTestResult } from '../../api.js';
+import { ProviderCard } from './ProviderCard.js';
+
+export function ProviderGroup({ label, icon, items, toggle, switchAnim, busy, testingId, testResults, onToggle, onSaveModel, onRemove, onTest, onOpenKey }: {
+  label: string;
+  icon: string;
+  items: AiProviderView[];
+  toggle: ToggleStyle;
+  switchAnim: Record<string, 'out' | 'in' | null>;
+  busy: boolean;
+  testingId: string | null;
+  testResults: Record<string, AiProviderTestResult>;
+  onToggle: (p: AiProviderView) => void;
+  onSaveModel: (p: AiProviderView, model: string) => void;
+  onRemove: (id: string) => void;
+  onTest: (p: AiProviderView) => void;
+  onOpenKey: (p: AiProviderView) => void;
+}) {
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center gap-2">
+        <span className="text-sm text-slate-300">{icon}</span>
+        <h4 className="glass-h3">{label}</h4>
+        <span className="glass-chip text-xs">{items.length}</span>
+      </div>
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+        {items.map((p) => (
+          <ProviderCard
+            key={p.id}
+            provider={p}
+            toggle={toggle}
+            anim={switchAnim[p.id] ?? null}
+            busy={busy}
+            isCustom={!BUILTIN_PROVIDER_IDS.has(p.id)}
+            testing={testingId === p.id}
+            testResult={testResults[p.id]}
+            onToggle={() => onToggle(p)}
+            onSaveModel={(m) => onSaveModel(p, m)}
+            onRemove={() => onRemove(p.id)}
+            onTest={() => onTest(p)}
+            onOpenKey={() => onOpenKey(p)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/templates/base/apps/admin/src/pages/ai/ProviderKeyDialog.tsx

@@ -0,0 +1,66 @@
+import React, { useEffect } from 'react';
+import type { AiProviderView } from '../../api.js';
+
+export function ProviderKeyDialog({ provider, value, onChange, onSave, onCancel, busy }: {
+  provider: AiProviderView;
+  value: string;
+  onChange: (value: string) => void;
+  onSave: () => void;
+  onCancel: () => void;
+  busy: boolean;
+}) {
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onCancel();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onCancel]);
+
+  return (
+    <div className="provider-modal-backdrop" onClick={onCancel}>
+      <div className="provider-modal space-y-4" role="dialog" aria-modal="true" aria-labelledby="provider-key-title" onClick={(event) => event.stopPropagation()}>
+        <div className="flex items-start justify-between gap-3">
+          <div>
+            <span className="admin-overline">API CREDENTIAL</span>
+            <h3 id="provider-key-title" className="mt-1 text-base font-semibold text-slate-100">{provider.label}</h3>
+            <code className="text-xs text-slate-500">{provider.id}</code>
+          </div>
+          <button type="button" onClick={onCancel} disabled={busy} className="glass-chip-btn text-xs" aria-label="Close API key dialog">✕</button>
+        </div>
+
+        <div className="rounded-xl border border-sky-400/20 bg-black/20 px-3 py-2 text-xs text-slate-400">
+          {provider.hasApiKey ? 'A key is already configured. Enter a new key to replace it.' : 'This key is stored server-side in .env and is never written to the config file.'}
+        </div>
+
+        <label className="block">
+          <span className="admin-overline">API key</span>
+          <input
+            className="glass-input mt-1 text-sm"
+            type="password"
+            id="ai-provider-api-key"
+            name="ai-provider-api-key"
+            autoComplete="new-password"
+            autoFocus
+            placeholder={provider.hasApiKey ? '•••••••• (enter new to replace)' : 'paste API key'}
+            value={value}
+            onChange={(event) => onChange(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' && value.trim() && !busy) {
+                event.preventDefault();
+                onSave();
+              }
+            }}
+          />
+        </label>
+
+        <div className="flex justify-end gap-2 border-t border-sky-400/20 pt-3">
+          <button type="button" onClick={onCancel} disabled={busy} className="glass-chip-btn">Cancel</button>
+          <button type="button" onClick={onSave} disabled={busy || !value.trim()} className="glass-btn-primary !py-1.5 text-sm">
+            {busy ? 'Saving…' : 'Save API key'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}