@skaile/forge-settings 0.0.0-stage → 1.0.0

package/src/runtime/vue/useProvidersPanel.ts

@@ -0,0 +1,1087 @@
+/**
+ * Shared brain for `components-nuxt-ui/ForgeProvidersPanel.vue` — the settings
+ * modal's Providers tab.
+ *
+ * It drives the registry editor: loading, the add/edit form, the delete confirmation,
+ * the "detected in environment" one-click adds, the per-row credential picker,
+ * the enabled toggle and every request live here.
+ *
+ * The panel writes one registry document — the scope's own `layer` — through
+ * `PUT|DELETE ${providersWriteUrl}/:id`. An entry a lower layer defines can be
+ * patched at workspace scope (`credential` / `enabled` only) and reset by
+ * deleting the patch. A key typed into the panel goes to the scope's `.env`
+ * route only; the provider route receives an `env:NAME` reference, never a
+ * value.
+ */
+
+import { $fetch } from "ofetch";
+import {
+  type ComputedRef,
+  computed,
+  onMounted,
+  type Ref,
+  reactive,
+  ref,
+  type WritableComputedRef,
+  watch,
+} from "vue";
+import {
+  type EnvLayerId,
+  type EnvSettingsDocument,
+  type EnvSettingsUpdate,
+  type EnvVarView,
+  validateEnvVarName,
+} from "../shared/env-vars";
+import {
+  AI_PROVIDER_SURFACES,
+  type AIProviderCredentialKind,
+  type AIProviderKind,
+  type AIProviderSurface,
+  validateCredentialRef,
+} from "../shared/provider-registry";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Registry document a provider entry is defined in. */
+export type ProvidersPanelLayer = "instance" | "workspace";
+
+/** Props both `ForgeProvidersPanel` variants declare. */
+export interface ProvidersPanelProps {
+  /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). */
+  providersUrl: string;
+  /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. */
+  providersWriteUrl: string;
+  /** Catalog preset summaries. Default `/api/providers/presets`. */
+  presetsUrl?: string;
+  /**
+   * The scope's `.env` route. `GET` on load and after every write; keys typed
+   * into the panel write through it. Omitted, no key can be entered.
+   */
+  environmentUrl?: string;
+  /** The scope's own registry document. */
+  layer: ProvidersPanelLayer;
+  /** Disables every write (non-admin at instance scope; provider lock). */
+  readOnly?: boolean;
+}
+
+/** Emits both variants declare. */
+export type ProvidersPanelEmit = (event: "changed") => void;
+
+/** One entry of `GET ${providersUrl}?all=1`. */
+export interface ProvidersPanelEntry {
+  id: string;
+  /** The entry's label, else its id. */
+  name: string;
+  kind: AIProviderKind;
+  /** Whether the credential reference resolved on the server. */
+  configured: boolean;
+  /** Why it did not resolve. Secret-free. */
+  error?: string;
+  credentialRef?: string;
+  credentialKind?: AIProviderCredentialKind;
+  hasEnvKey: boolean;
+  envKeyName?: string;
+  baseUrl?: string;
+  preset?: string;
+  surface?: AIProviderSurface;
+  enabled: boolean;
+  locked: boolean;
+  /** Registry documents holding the id, lowest first: `["instance"]`, `["workspace"]` or both. */
+  layers: ProvidersPanelLayer[];
+  /** The scope's own document's values for the editable fields the dialog does not show. */
+  layerFields?: Record<string, unknown>;
+}
+
+/** One catalog preset, as `GET /api/providers/presets` and `.../detected` list it. */
+export interface ProvidersPanelPreset {
+  id: string;
+  label: string;
+  kind: AIProviderKind;
+  surface?: AIProviderSurface;
+  base_url?: string;
+  base_url_env?: string;
+  credential: { kind: AIProviderCredentialKind; env?: string };
+}
+
+/** Where a row's entry lives relative to the scope's own document. */
+export type ProvidersPanelRowState = "own" | "inherited" | "patched";
+
+/** One entry of a row's credential select. */
+export interface ProvidersPanelCredentialOption {
+  /** An env var NAME, a literal non-env ref, {@link CREDENTIAL_ENTER_KEY} or {@link CREDENTIAL_OTHER_REF}. */
+  value: string;
+  /** `NAME ••••hint` | `NAME (not set)` | the literal ref | `Enter a key…` | `Other reference…`. */
+  label: string;
+  defined?: boolean;
+  hint?: string;
+  source?: EnvLayerId;
+  action?: "enter-key" | "other-ref";
+}
+
+/** A table row: the entry plus what the panel derives for it. */
+export interface ProvidersPanelRow extends ProvidersPanelEntry {
+  /** Own entry, an inherited one, or an inherited one this scope patched. */
+  state: ProvidersPanelRowState;
+  /** `instance` | `workspace` | `instance · overridden here`. */
+  badge: string;
+  /** Set on inherited rows. */
+  inheritedNote?: string;
+  /** Edit/Delete offered: the scope's document defines it and the panel is writable. */
+  editable: boolean;
+  /** Reset offered: a patched row of a writable panel. */
+  canReset: boolean;
+  /** The enabled switch is live. */
+  canToggle: boolean;
+  /** The entry takes a credential (its kind is not `none`). */
+  needsCredential: boolean;
+  /** The credential picker is live. */
+  canEditCredential: boolean;
+  /** The select's model: the env var NAME of an `env:` ref, else the literal ref, else `""`. */
+  credentialValue: string;
+  credentialOptions: ProvidersPanelCredentialOption[];
+  /** The preset it inherits, else its surface, else its kind. */
+  origin: string;
+  /** `configured · <source>`, `missing <VAR>`, the resolver's reason, or `No credential needed.`. */
+  status: string;
+  /** Which other layer defines or overrides the credential; see the panel contract. */
+  overrideNotices: string[];
+}
+
+/** The add/edit dialog's fields. */
+export interface ProvidersPanelForm {
+  /** A preset id, or {@link CUSTOM_PRESET}. */
+  preset: string;
+  id: string;
+  /** Custom entries only. */
+  surface: string;
+  /** Empty: the preset's endpoint. */
+  baseUrl: string;
+  /** Adding only: the `env:` variable the credential references. */
+  envName: string;
+  /** Adding only, "Set value now": written to the scope's `.env`, never to the provider route. */
+  secret: string;
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+/** The preset select's value for an entry that names no preset. */
+export const CUSTOM_PRESET = "__custom__";
+
+/** Credential select value: open the inline key editor. */
+export const CREDENTIAL_ENTER_KEY = "__enter_key__";
+
+/** Credential select value: open the inline reference editor. */
+export const CREDENTIAL_OTHER_REF = "__other_ref__";
+
+/** Registry ids the write routes accept (`isSafeProviderId` upstream). */
+const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+
+const DEFAULT_PRESETS_URL = "/api/providers/presets";
+
+/** An `env:NAME` credential reference; group 1 is the variable name. */
+const ENV_REF_PATTERN = /^env:(.+)$/;
+
+/** The credential kind a written reference gets when the row states none. */
+const FALLBACK_CREDENTIAL_KIND: AIProviderCredentialKind = "api_key_header";
+
+const ENV_SOURCE_LABEL: Record<EnvLayerId, string> = {
+  instance: "instance .env",
+  workspace: "workspace .env",
+  process: "boot environment",
+};
+
+const OVERRIDES_INSTANCE_NOTICE =
+  "Entering a key here stores it in this workspace's .env and overrides that value for this workspace.";
+
+/**
+ * The server's refusal for a failed request, else `fallback`. A registry
+ * rejection (`400` with `data.diagnostics`) reads as its diagnostics' messages.
+ */
+function requestErrorMessage(err: unknown, fallback: string): string {
+  const e = err as {
+    data?: { statusMessage?: unknown; data?: { diagnostics?: Array<{ message?: unknown }> } };
+    statusMessage?: unknown;
+  } | null;
+  const details = (e?.data?.data?.diagnostics ?? [])
+    .map((d) => d.message)
+    .filter((m): m is string => typeof m === "string" && m !== "");
+  if (details.length > 0) return details.join("; ");
+  const message = e?.data?.statusMessage ?? e?.statusMessage;
+  return typeof message === "string" && message ? message : fallback;
+}
+
+/** The variable name of an `env:NAME` reference. */
+function envNameOfRef(ref: string | undefined): string | undefined {
+  return ref ? ENV_REF_PATTERN.exec(ref)?.[1] : undefined;
+}
+
+/** `configured · …` for a reference that is not an env var. */
+function nonEnvSourceLabel(ref: string): string | undefined {
+  if (ref.startsWith("keyring:")) return "keyring";
+  if (ref.startsWith("cmd:")) return "runtime-owned (cmd)";
+  if (ref.startsWith("platform:")) return "control-plane-owned (platform)";
+  return undefined;
+}
+
+const EMPTY_FORM: Readonly<ProvidersPanelForm> = {
+  preset: "",
+  id: "",
+  surface: "",
+  baseUrl: "",
+  envName: "",
+  secret: "",
+};
+
+/** What both `ForgeProvidersPanel` variants bind to. */
+export interface ProvidersPanelState {
+  /** The scope's entries, disabled ones included, in registry order. */
+  rows: ComputedRef<ProvidersPanelRow[]>;
+  loading: Ref<boolean>;
+  loadError: Ref<string | null>;
+  /** Re-read the entries, the detected presets and the environment document. */
+  refresh: () => Promise<void>;
+
+  dialogVisible: Ref<boolean>;
+  dialogTitle: ComputedRef<string>;
+  /** The row being edited; `null` while adding. */
+  editing: Ref<ProvidersPanelEntry | null>;
+  form: ProvidersPanelForm;
+  /** A refusal from the form check or either request, shown in the dialog. */
+  dialogError: Ref<string | null>;
+  saving: Ref<boolean>;
+  /** Catalog presets plus "Custom" ({@link CUSTOM_PRESET}). */
+  presetOptions: ComputedRef<Array<{ label: string; value: string }>>;
+  surfaceOptions: Array<{ label: string; value: AIProviderSurface }>;
+  isCustom: ComputedRef<boolean>;
+  /** The surface select is shown: a custom `llm`/`embed` entry. */
+  showSurface: ComputedRef<boolean>;
+  baseUrlPlaceholder: ComputedRef<string>;
+  /** "Set value now" is offered: the scope has an `.env` route. */
+  canSetValue: ComputedRef<boolean>;
+  /** The dialog shows the env name and secret fields: adding, not editing. */
+  showCredentialFields: ComputedRef<boolean>;
+  idError: ComputedRef<string | null>;
+  openAdd: (presetId?: string) => void;
+  openEdit: (row: ProvidersPanelEntry) => void;
+  selectPreset: (value: string) => void;
+  saveProvider: () => Promise<void>;
+
+  deleteTarget: Ref<ProvidersPanelEntry | null>;
+  /** The confirmation dialog's `v-model`; closing it cancels. */
+  deleteOpen: WritableComputedRef<boolean>;
+  deleteError: Ref<string | null>;
+  deleting: Ref<boolean>;
+  requestDelete: (row: ProvidersPanelEntry) => void;
+  confirmDelete: () => Promise<void>;
+
+  /** Presets whose key is set in the scope's env and that no entry names. */
+  detected: Ref<ProvidersPanelPreset[]>;
+  /** Preset id whose one-click add is in flight. */
+  detectedBusy: Ref<string | null>;
+  detectedError: Ref<string | null>;
+  addDetected: (preset: ProvidersPanelPreset) => Promise<void>;
+
+  // Row actions
+  /** The credential select's `@update`: a NAME writes, the two actions open an editor. */
+  onCredentialSelect: (row: ProvidersPanelRow, value: string) => void;
+  setCredentialEnv: (row: ProvidersPanelRow, name: string) => Promise<void>;
+  setEnabled: (row: ProvidersPanelRow, enabled: boolean) => Promise<void>;
+  /** Delete the workspace patch of an inherited entry. */
+  resetPatch: (row: ProvidersPanelRow) => Promise<void>;
+  /** Row id with a write in flight. */
+  rowBusy: Ref<string | null>;
+  rowError: Ref<{ id: string; message: string } | null>;
+
+  // Inline key editor
+  /** "Enter a key…" is offered: the scope has an editable `.env` route. */
+  canEnterKey: ComputedRef<boolean>;
+  /** Row id whose key editor is open. */
+  keyEditing: Ref<string | null>;
+  keyForm: { name: string; value: string };
+  keyError: Ref<string | null>;
+  openKeyEditor: (row: ProvidersPanelRow) => void;
+  cancelKeyEditor: () => void;
+  saveKeyEditor: () => Promise<void>;
+
+  // Inline reference editor
+  /** Row id whose reference editor is open. */
+  refEditing: Ref<string | null>;
+  refForm: { ref: string };
+  refError: Ref<string | null>;
+  openRefEditor: (row: ProvidersPanelRow) => void;
+  cancelRefEditor: () => void;
+  saveRefEditor: () => Promise<void>;
+
+  // Environment
+  envDocument: Ref<EnvSettingsDocument | null>;
+  /** The environment document says the caller may write its layer. */
+  envEditable: ComputedRef<boolean>;
+  /** Draft new values per variable name. */
+  envValues: Record<string, string>;
+  envError: Ref<string | null>;
+  envBusy: Ref<boolean>;
+  setEnvValue: (name: string) => Promise<void>;
+}
+
+// ── Composable ───────────────────────────────────────────────────────────────
+
+export function useProvidersPanel(
+  props: ProvidersPanelProps,
+  emit: ProvidersPanelEmit,
+): ProvidersPanelState {
+  const providers = ref<ProvidersPanelEntry[]>([]);
+  const presets = ref<ProvidersPanelPreset[]>([]);
+  const detected = ref<ProvidersPanelPreset[]>([]);
+  const envDocument = ref<EnvSettingsDocument | null>(null);
+  const loading = ref(false);
+  const loadError = ref<string | null>(null);
+  const envError = ref<string | null>(null);
+
+  // ── Loading ────────────────────────────────────────────────────────────────
+
+  /** Read the scope's `.env` document. A failure shows in the disclosure and blocks nothing else. */
+  async function loadEnvironment() {
+    if (!props.environmentUrl) {
+      envDocument.value = null;
+      return;
+    }
+    try {
+      envDocument.value = (await $fetch(props.environmentUrl)) as EnvSettingsDocument;
+      envError.value = null;
+    } catch (err) {
+      envError.value = requestErrorMessage(err, "Could not load the environment variables.");
+    }
+  }
+
+  /** Re-read the entries (disabled ones included), the detected presets and the environment. */
+  async function refresh() {
+    loading.value = true;
+    loadError.value = null;
+    try {
+      const [list, found] = await Promise.all([
+        $fetch(props.providersUrl, { query: { all: "1" } }) as Promise<ProvidersPanelEntry[]>,
+        $fetch(`${props.providersWriteUrl}/detected`) as Promise<ProvidersPanelPreset[]>,
+        loadEnvironment(),
+      ]);
+      providers.value = Array.isArray(list) ? list : [];
+      detected.value = Array.isArray(found) ? found : [];
+    } catch (err) {
+      loadError.value = requestErrorMessage(err, "Could not load the providers.");
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function loadPresets() {
+    try {
+      const list = (await $fetch(
+        props.presetsUrl ?? DEFAULT_PRESETS_URL,
+      )) as ProvidersPanelPreset[];
+      presets.value = Array.isArray(list) ? list : [];
+    } catch (err) {
+      loadError.value = requestErrorMessage(err, "Could not load the provider presets.");
+    }
+  }
+
+  /** After every successful write: reload list, banner and environment, tell the host. */
+  async function afterWrite() {
+    await refresh();
+    emit("changed");
+  }
+
+  onMounted(() => {
+    void loadPresets();
+    void refresh();
+  });
+
+  watch(
+    () => [props.providersUrl, props.providersWriteUrl, props.environmentUrl],
+    () => void refresh(),
+  );
+
+  // ── Table ──────────────────────────────────────────────────────────────────
+
+  const envVars = computed(() => {
+    const byName = new Map<string, EnvVarView>();
+    for (const v of envDocument.value?.vars ?? []) byName.set(v.name, v);
+    return byName;
+  });
+
+  const envEditable = computed(() => envDocument.value?.editable === true);
+
+  const canEnterKey = computed(
+    () => Boolean(props.environmentUrl) && envDocument.value?.editable !== false,
+  );
+
+  /** Where an entry lives relative to this scope's own document. */
+  function stateOf(entry: Pick<ProvidersPanelEntry, "layers">): ProvidersPanelRowState {
+    if (props.layer !== "workspace" || !entry.layers.includes("instance")) return "own";
+    return entry.layers.includes("workspace") ? "patched" : "inherited";
+  }
+
+  /** Whether the scope's own document defines the entry and the panel may write it. */
+  function isEditable(entry: ProvidersPanelEntry): boolean {
+    return !props.readOnly && !entry.locked && stateOf(entry) === "own";
+  }
+
+  /** The select's options: every env var name worth offering, then the literal ref and the two actions. */
+  function credentialOptionsOf(entry: ProvidersPanelEntry): ProvidersPanelCredentialOption[] {
+    const doc = envDocument.value;
+    const currentEnv = envNameOfRef(entry.credentialRef);
+    const names = new Set<string>();
+    for (const v of doc?.vars ?? []) names.add(v.name);
+    for (const m of doc?.missing ?? []) names.add(m.name);
+    const rowPresetEnv = presets.value.find((p) => p.id === entry.preset)?.credential.env;
+    if (rowPresetEnv) names.add(rowPresetEnv);
+    for (const p of detected.value) if (p.credential.env) names.add(p.credential.env);
+    if (currentEnv) names.add(currentEnv);
+
+    const options: ProvidersPanelCredentialOption[] = [...names].sort().map((name) => {
+      const v = envVars.value.get(name);
+      if (!doc) return { value: name, label: name };
+      if (!v) return { value: name, label: `${name} (not set)`, defined: false };
+      return {
+        value: name,
+        label: v.hint ? `${name} ••••${v.hint}` : name,
+        defined: true,
+        hint: v.hint,
+        source: v.source,
+      };
+    });
+    if (entry.credentialRef && !currentEnv) {
+      options.push({ value: entry.credentialRef, label: entry.credentialRef });
+    }
+    if (canEnterKey.value) {
+      options.push({ value: CREDENTIAL_ENTER_KEY, label: "Enter a key…", action: "enter-key" });
+    }
+    options.push({ value: CREDENTIAL_OTHER_REF, label: "Other reference…", action: "other-ref" });
+    return options;
+  }
+
+  function statusOf(entry: ProvidersPanelEntry, needsCredential: boolean): string {
+    if (!needsCredential) return "No credential needed.";
+    const ref = entry.credentialRef;
+    const envName = envNameOfRef(ref);
+    if (entry.configured) {
+      const source = envName
+        ? (() => {
+            const v = envVars.value.get(envName);
+            return v ? ENV_SOURCE_LABEL[v.source] : undefined;
+          })()
+        : ref
+          ? nonEnvSourceLabel(ref)
+          : undefined;
+      return source ? `configured · ${source}` : "configured";
+    }
+    const missing = envName ?? entry.envKeyName;
+    return missing ? `missing ${missing}` : (entry.error ?? "not configured");
+  }
+
+  function overrideNoticesOf(entry: ProvidersPanelEntry): string[] {
+    const notices: string[] = [];
+    const envName = envNameOfRef(entry.credentialRef);
+    const v = envName ? envVars.value.get(envName) : undefined;
+    if (v && v.shadows.length > 0) {
+      notices.push(`Also defined in ${v.shadows.join(", ")}; the ${v.source} value is used.`);
+    }
+    if (v && props.layer === "workspace" && (v.source === "instance" || v.source === "process")) {
+      notices.push(OVERRIDES_INSTANCE_NOTICE);
+    }
+    if (entry.locked) notices.push("Locked by the control plane.");
+    return notices;
+  }
+
+  function buildRow(entry: ProvidersPanelEntry): ProvidersPanelRow {
+    const state = stateOf(entry);
+    const writable = !props.readOnly && !entry.locked;
+    const needsCredential = entry.credentialKind !== "none";
+    const envName = envNameOfRef(entry.credentialRef);
+    return {
+      ...entry,
+      state,
+      badge:
+        state === "patched"
+          ? "instance · overridden here"
+          : state === "inherited"
+            ? "instance"
+            : props.layer,
+      inheritedNote: state === "inherited" ? "Inherited from the instance." : undefined,
+      editable: writable && state === "own",
+      canReset: writable && state === "patched",
+      canToggle: writable,
+      needsCredential,
+      canEditCredential: needsCredential && writable,
+      credentialValue: envName ?? entry.credentialRef ?? "",
+      credentialOptions: needsCredential ? credentialOptionsOf(entry) : [],
+      origin: entry.preset ?? entry.surface ?? entry.kind,
+      status: statusOf(entry, needsCredential),
+      overrideNotices: overrideNoticesOf(entry),
+    };
+  }
+
+  const rows = computed<ProvidersPanelRow[]>(() => providers.value.map(buildRow));
+
+  // ── Add / edit dialog ──────────────────────────────────────────────────────
+
+  const dialogVisible = ref(false);
+  /** The row being edited; `null` while adding. */
+  const editing = ref<ProvidersPanelEntry | null>(null);
+  const form = reactive<ProvidersPanelForm>({ ...EMPTY_FORM });
+  const dialogError = ref<string | null>(null);
+  const saving = ref(false);
+
+  const presetOptions = computed(() => [
+    ...presets.value.map((preset) => ({ label: preset.label, value: preset.id })),
+    { label: "Custom", value: CUSTOM_PRESET },
+  ]);
+
+  const surfaceOptions = AI_PROVIDER_SURFACES.map((surface) => ({
+    label: surface,
+    value: surface,
+  }));
+
+  const selectedPreset = computed(() => presets.value.find((preset) => preset.id === form.preset));
+
+  const isCustom = computed(() => form.preset === CUSTOM_PRESET);
+
+  /** Kind of a custom entry: the edited one's, else `llm`. */
+  const customKind = computed<AIProviderKind>(() => editing.value?.kind ?? "llm");
+
+  /** Custom `llm`/`embed` entries name their wire protocol; voice entries have none. */
+  const showSurface = computed(
+    () => isCustom.value && (customKind.value === "llm" || customKind.value === "embed"),
+  );
+
+  const baseUrlPlaceholder = computed(
+    () => selectedPreset.value?.base_url ?? "https://api.example.com/v1",
+  );
+
+  /** Whether "Set value now" is offered: the scope has an `.env` route. */
+  const canSetValue = computed(() => Boolean(props.environmentUrl));
+
+  /** The dialog collects a credential for a new entry only. */
+  const showCredentialFields = computed(() => editing.value === null);
+
+  const idError = computed(() => {
+    const id = form.id.trim();
+    return id && !PROVIDER_ID_PATTERN.test(id)
+      ? "Use lower-case letters, digits, '-' and '_', starting with a letter or digit."
+      : null;
+  });
+
+  const dialogTitle = computed(() =>
+    editing.value ? `Edit provider — ${editing.value.id}` : "Add provider",
+  );
+
+  function resetDialog(values: Partial<ProvidersPanelForm>, row: ProvidersPanelEntry | null) {
+    Object.assign(form, EMPTY_FORM, values);
+    editing.value = row;
+    dialogError.value = null;
+    dialogVisible.value = true;
+  }
+
+  /** Open the add dialog, optionally on a preset. */
+  function openAdd(presetId?: string) {
+    if (props.readOnly) return;
+    resetDialog({}, null);
+    if (presetId) selectPreset(presetId);
+  }
+
+  /** Open the dialog on an entry this scope's document defines; its id stays fixed. */
+  function openEdit(row: ProvidersPanelEntry) {
+    if (!isEditable(row)) return;
+    const preset = presets.value.find((p) => p.id === row.preset);
+    resetDialog(
+      {
+        preset: preset ? preset.id : CUSTOM_PRESET,
+        id: row.id,
+        surface: row.surface ?? "",
+        // The preset's own endpoint shows as the placeholder, not as a pinned value.
+        baseUrl: row.baseUrl && row.baseUrl !== preset?.base_url ? row.baseUrl : "",
+      },
+      row,
+    );
+  }
+
+  /**
+   * Switch the preset. Fields still holding the previous preset's defaults
+   * (the id while adding, the env var, a custom surface) follow the new one;
+   * anything the user typed is kept.
+   */
+  function selectPreset(value: string) {
+    const previous = selectedPreset.value;
+    const next = presets.value.find((preset) => preset.id === value);
+    form.preset = value;
+    if (!editing.value && (form.id === "" || form.id === previous?.id)) form.id = next?.id ?? "";
+    if (form.envName === "" || form.envName === previous?.credential.env)
+      form.envName = next?.credential.env ?? "";
+    if (value === CUSTOM_PRESET && form.surface === "") form.surface = previous?.surface ?? "";
+  }
+
+  /** Why the form cannot be saved, or `null`. */
+  function formRefusal(): string | null {
+    if (!form.preset) return "Choose a preset or Custom.";
+    if (!form.id.trim()) return "Enter a provider id.";
+    if (idError.value) return idError.value;
+    if (showSurface.value && !form.surface) return "Choose the surface a custom provider speaks.";
+    if (isCustom.value && !form.baseUrl.trim()) return "A custom provider needs a base URL.";
+    if (showCredentialFields.value) {
+      const envName = form.envName.trim();
+      if (envName) {
+        const refusal = validateEnvVarName(envName);
+        if (refusal) return refusal;
+      }
+      if (form.secret && !envName) return "Name the environment variable the value is stored in.";
+    }
+    return null;
+  }
+
+  /**
+   * The `PUT ${providersWriteUrl}/:id` body. The write replaces every editable
+   * field, so an edit starts from the defining document's values the dialog
+   * does not show (`layerFields`) and keeps the stored credential.
+   */
+  function buildBody(): Record<string, unknown> {
+    const row = editing.value;
+    const body: Record<string, unknown> = { ...(row?.layerFields ?? {}) };
+    const preset = selectedPreset.value;
+    // Facts of the edited entry only carry over while it keeps its preset (or stays custom).
+    const kept = row && form.preset === (row.preset ?? CUSTOM_PRESET) ? row : null;
+    if (isCustom.value) {
+      body.kind = customKind.value;
+      if (showSurface.value) body.surface = form.surface;
+    } else {
+      body.preset = form.preset;
+      // A surface the entry overrode over its preset's survives the edit.
+      if (kept?.surface && kept.surface !== preset?.surface) body.surface = kept.surface;
+    }
+    const baseUrl = form.baseUrl.trim();
+    if (baseUrl) body.base_url = baseUrl;
+    const credentialKind: AIProviderCredentialKind =
+      kept?.credentialKind ?? (isCustom.value ? "bearer" : (preset?.credential.kind ?? "bearer"));
+    const envName = row ? "" : form.envName.trim();
+    if (envName) body.credential = { kind: credentialKind, ref: `env:${envName}` };
+    else if (row?.credentialRef) body.credential = { kind: credentialKind, ref: row.credentialRef };
+    return body;
+  }
+
+  /**
+   * Save the dialog. A "Set value now" secret is written first, through the
+   * scope's `.env` route as `NAME=value`; only then is the entry — carrying
+   * the `env:NAME` reference — written. Refusals from either request stay
+   * inline in the dialog.
+   */
+  async function saveProvider() {
+    if (props.readOnly) return;
+    const refusal = formRefusal();
+    if (refusal) {
+      dialogError.value = refusal;
+      return;
+    }
+    const id = form.id.trim();
+    saving.value = true;
+    dialogError.value = null;
+    try {
+      if (showCredentialFields.value && form.secret && props.environmentUrl) {
+        const update: EnvSettingsUpdate = {
+          set: { [form.envName.trim()]: form.secret },
+          unset: [],
+        };
+        await $fetch(props.environmentUrl, { method: "PUT", body: update });
+        form.secret = "";
+      }
+      await $fetch(`${props.providersWriteUrl}/${encodeURIComponent(id)}`, {
+        method: "PUT",
+        body: buildBody(),
+      });
+      dialogVisible.value = false;
+      editing.value = null;
+      await afterWrite();
+    } catch (err) {
+      dialogError.value = requestErrorMessage(err, "Could not save the provider.");
+    } finally {
+      saving.value = false;
+    }
+  }
+
+  // ── Delete ─────────────────────────────────────────────────────────────────
+
+  const deleteTarget = ref<ProvidersPanelEntry | null>(null);
+  const deleteError = ref<string | null>(null);
+  const deleting = ref(false);
+
+  /** The confirm dialog's `v-model`. Closing it cancels the delete. */
+  const deleteOpen = computed({
+    get: () => deleteTarget.value !== null,
+    set: (open: boolean) => {
+      if (!open) deleteTarget.value = null;
+    },
+  });
+
+  function requestDelete(row: ProvidersPanelEntry) {
+    if (!isEditable(row)) return;
+    deleteError.value = null;
+    deleteTarget.value = row;
+  }
+
+  async function confirmDelete() {
+    const target = deleteTarget.value;
+    if (!target || props.readOnly) return;
+    deleting.value = true;
+    deleteError.value = null;
+    try {
+      await $fetch(`${props.providersWriteUrl}/${encodeURIComponent(target.id)}`, {
+        method: "DELETE",
+      });
+      deleteTarget.value = null;
+      await afterWrite();
+    } catch (err) {
+      deleteError.value = requestErrorMessage(err, `Could not delete ${target.id}.`);
+    } finally {
+      deleting.value = false;
+    }
+  }
+
+  // ── Detected in environment ────────────────────────────────────────────────
+
+  /** Preset id whose one-click add is in flight. */
+  const detectedBusy = ref<string | null>(null);
+  const detectedError = ref<string | null>(null);
+
+  /**
+   * Add a detected preset the way boot seeding would:
+   * `{ preset, credential: { kind, ref: "env:<VAR>" } }` under the preset id,
+   * or `<preset>-env` when an entry already holds that id. With both taken the
+   * add dialog opens on the preset instead.
+   */
+  async function addDetected(preset: ProvidersPanelPreset) {
+    if (props.readOnly) return;
+    const taken = new Set(providers.value.map((entry) => entry.id));
+    const id = [preset.id, `${preset.id}-env`].find((candidate) => !taken.has(candidate));
+    const envName = preset.credential.env;
+    if (!id || !envName) {
+      openAdd(preset.id);
+      return;
+    }
+    detectedBusy.value = preset.id;
+    detectedError.value = null;
+    try {
+      await $fetch(`${props.providersWriteUrl}/${encodeURIComponent(id)}`, {
+        method: "PUT",
+        body: {
+          preset: preset.id,
+          credential: { kind: preset.credential.kind, ref: `env:${envName}` },
+        },
+      });
+      await afterWrite();
+    } catch (err) {
+      detectedError.value = requestErrorMessage(err, `Could not add ${preset.label}.`);
+    } finally {
+      detectedBusy.value = null;
+    }
+  }
+
+  // ── Row actions ────────────────────────────────────────────────────────────
+
+  const rowBusy = ref<string | null>(null);
+  const rowError = ref<{ id: string; message: string } | null>(null);
+
+  /**
+   * The full body of an own entry, rebuilt from its row the way the dialog
+   * builds one: an own write replaces every editable field, so everything the
+   * row shows is sent back.
+   */
+  function ownBody(row: ProvidersPanelEntry): Record<string, unknown> {
+    const body: Record<string, unknown> = { ...(row.layerFields ?? {}) };
+    const preset = presets.value.find((p) => p.id === row.preset);
+    if (row.preset) {
+      body.preset = row.preset;
+      if (row.surface && row.surface !== preset?.surface) body.surface = row.surface;
+    } else {
+      body.kind = row.kind;
+      if (row.surface) body.surface = row.surface;
+    }
+    if (row.baseUrl && row.baseUrl !== preset?.base_url) body.base_url = row.baseUrl;
+    if (row.credentialRef) {
+      body.credential = {
+        kind: row.credentialKind ?? FALLBACK_CREDENTIAL_KIND,
+        ref: row.credentialRef,
+      };
+    }
+    return body;
+  }
+
+  /**
+   * `PUT` a credential and/or enabled change. An own row sends its full body
+   * with the change applied; an inherited or patched row sends only the
+   * change, which the server merges into the workspace patch.
+   */
+  async function putRowChange(
+    row: ProvidersPanelRow,
+    change: { credential?: { kind: AIProviderCredentialKind; ref: string }; enabled?: boolean },
+  ) {
+    const body = row.state === "own" ? { ...ownBody(row), ...change } : change;
+    await $fetch(`${props.providersWriteUrl}/${encodeURIComponent(row.id)}`, {
+      method: "PUT",
+      body,
+    });
+  }
+
+  function credentialFor(row: ProvidersPanelRow, ref: string) {
+    return { kind: row.credentialKind ?? FALLBACK_CREDENTIAL_KIND, ref };
+  }
+
+  /** Run one row's write, then reload and tell the host; a refusal lands in {@link rowError}. */
+  async function runRowWrite(id: string, work: () => Promise<void>, fallback: string) {
+    rowBusy.value = id;
+    rowError.value = null;
+    try {
+      await work();
+      await afterWrite();
+    } catch (err) {
+      rowError.value = { id, message: requestErrorMessage(err, fallback) };
+    } finally {
+      rowBusy.value = null;
+    }
+  }
+
+  async function setCredentialEnv(row: ProvidersPanelRow, name: string) {
+    if (!row.canEditCredential) return;
+    const ref = `env:${name}`;
+    if (row.credentialRef === ref) return;
+    await runRowWrite(
+      row.id,
+      () => putRowChange(row, { credential: credentialFor(row, ref) }),
+      `Could not change the credential of ${row.id}.`,
+    );
+  }
+
+  async function setEnabled(row: ProvidersPanelRow, enabled: boolean) {
+    if (!row.canToggle) return;
+    await runRowWrite(
+      row.id,
+      () => putRowChange(row, { enabled }),
+      `Could not ${enabled ? "enable" : "disable"} ${row.id}.`,
+    );
+  }
+
+  async function resetPatch(row: ProvidersPanelRow) {
+    if (!row.canReset) return;
+    await runRowWrite(
+      row.id,
+      async () => {
+        await $fetch(`${props.providersWriteUrl}/${encodeURIComponent(row.id)}`, {
+          method: "DELETE",
+        });
+      },
+      `Could not reset ${row.id}.`,
+    );
+  }
+
+  // ── Inline key editor ──────────────────────────────────────────────────────
+
+  const keyEditing = ref<string | null>(null);
+  const keyForm = reactive({ name: "", value: "" });
+  const keyError = ref<string | null>(null);
+
+  const refEditing = ref<string | null>(null);
+  const refForm = reactive({ ref: "" });
+  const refError = ref<string | null>(null);
+
+  function cancelKeyEditor() {
+    keyEditing.value = null;
+    keyForm.name = "";
+    keyForm.value = "";
+    keyError.value = null;
+  }
+
+  function cancelRefEditor() {
+    refEditing.value = null;
+    refForm.ref = "";
+    refError.value = null;
+  }
+
+  /** Open the key editor, name prefilled: the row's env var, else its preset's conventional one. */
+  function openKeyEditor(row: ProvidersPanelRow) {
+    if (!row.canEditCredential || !canEnterKey.value) return;
+    cancelRefEditor();
+    cancelKeyEditor();
+    const presetEnv = presets.value.find((p) => p.id === row.preset)?.credential.env;
+    keyForm.name = envNameOfRef(row.credentialRef) ?? presetEnv ?? "";
+    keyEditing.value = row.id;
+  }
+
+  /**
+   * Save the key: `NAME=value` into the scope's `.env` first, then the row's
+   * reference when it is not `env:NAME` already. The value never reaches the
+   * provider route.
+   */
+  async function saveKeyEditor() {
+    const row = rows.value.find((r) => r.id === keyEditing.value);
+    if (!row?.canEditCredential || !props.environmentUrl) return;
+    const name = keyForm.name.trim();
+    const refusal = validateEnvVarName(name);
+    if (refusal) {
+      keyError.value = refusal;
+      return;
+    }
+    if (!keyForm.value) {
+      keyError.value = "Enter the key.";
+      return;
+    }
+    rowBusy.value = row.id;
+    keyError.value = null;
+    let wroteEnv = false;
+    try {
+      const update: EnvSettingsUpdate = { set: { [name]: keyForm.value }, unset: [] };
+      await $fetch(props.environmentUrl, { method: "PUT", body: update });
+      wroteEnv = true;
+      const ref = `env:${name}`;
+      if (row.credentialRef !== ref) {
+        await putRowChange(row, { credential: credentialFor(row, ref) });
+      }
+      cancelKeyEditor();
+    } catch (err) {
+      keyError.value = requestErrorMessage(err, "Could not save the key.");
+    } finally {
+      rowBusy.value = null;
+    }
+    if (wroteEnv) await afterWrite();
+  }
+
+  // ── Inline reference editor ────────────────────────────────────────────────
+
+  function openRefEditor(row: ProvidersPanelRow) {
+    if (!row.canEditCredential) return;
+    cancelKeyEditor();
+    cancelRefEditor();
+    refForm.ref = row.credentialRef && !envNameOfRef(row.credentialRef) ? row.credentialRef : "";
+    refEditing.value = row.id;
+  }
+
+  async function saveRefEditor() {
+    const row = rows.value.find((r) => r.id === refEditing.value);
+    if (!row?.canEditCredential) return;
+    const ref = refForm.ref.trim();
+    const refusal = ref ? validateCredentialRef(ref) : "Enter a reference.";
+    if (refusal) {
+      refError.value = refusal;
+      return;
+    }
+    rowBusy.value = row.id;
+    refError.value = null;
+    try {
+      await putRowChange(row, { credential: credentialFor(row, ref) });
+      cancelRefEditor();
+      await afterWrite();
+    } catch (err) {
+      refError.value = requestErrorMessage(err, "Could not save the reference.");
+    } finally {
+      rowBusy.value = null;
+    }
+  }
+
+  function onCredentialSelect(row: ProvidersPanelRow, value: string) {
+    if (value === CREDENTIAL_ENTER_KEY) openKeyEditor(row);
+    else if (value === CREDENTIAL_OTHER_REF) openRefEditor(row);
+    else if (value !== row.credentialValue) void setCredentialEnv(row, value);
+  }
+
+  // ── Environment writes ─────────────────────────────────────────────────────
+
+  const envValues = reactive<Record<string, string>>({});
+  const envBusy = ref(false);
+
+  /** Write one change to the scope's `.env`, then reload and tell the host. */
+  async function writeEnvironment(update: EnvSettingsUpdate, fallback: string): Promise<boolean> {
+    if (!props.environmentUrl || !envEditable.value) return false;
+    envBusy.value = true;
+    envError.value = null;
+    try {
+      await $fetch(props.environmentUrl, { method: "PUT", body: update });
+    } catch (err) {
+      envError.value = requestErrorMessage(err, fallback);
+      return false;
+    } finally {
+      envBusy.value = false;
+    }
+    await afterWrite();
+    return true;
+  }
+
+  async function setEnvValue(name: string) {
+    const value = envValues[name];
+    if (!value) return;
+    if (await writeEnvironment({ set: { [name]: value }, unset: [] }, `Could not save ${name}.`)) {
+      delete envValues[name];
+    }
+  }
+
+  return {
+    // table
+    rows,
+    loading,
+    loadError,
+    refresh,
+    // dialog
+    dialogVisible,
+    dialogTitle,
+    editing,
+    form,
+    dialogError,
+    saving,
+    presetOptions,
+    surfaceOptions,
+    isCustom,
+    showSurface,
+    baseUrlPlaceholder,
+    canSetValue,
+    showCredentialFields,
+    idError,
+    openAdd,
+    openEdit,
+    selectPreset,
+    saveProvider,
+    // delete
+    deleteTarget,
+    deleteOpen,
+    deleteError,
+    deleting,
+    requestDelete,
+    confirmDelete,
+    // detected
+    detected,
+    detectedBusy,
+    detectedError,
+    addDetected,
+    // row actions
+    onCredentialSelect,
+    setCredentialEnv,
+    setEnabled,
+    resetPatch,
+    rowBusy,
+    rowError,
+    // key editor
+    canEnterKey,
+    keyEditing,
+    keyForm,
+    keyError,
+    openKeyEditor,
+    cancelKeyEditor,
+    saveKeyEditor,
+    // reference editor
+    refEditing,
+    refForm,
+    refError,
+    openRefEditor,
+    cancelRefEditor,
+    saveRefEditor,
+    // environment
+    envDocument,
+    envEditable,
+    envValues,
+    envError,
+    envBusy,
+    setEnvValue,
+  };
+}