@skaile/forge-settings 0.0.0-stage → 1.0.0

package/dist/runtime/server/provider-discovery.js

@@ -0,0 +1,77 @@
+import { resolveEntryBaseUrl } from "@skaile/workspaces/core";
+import { fetchProviderModels, getStaticModels } from "@skaile/workspaces/sdk/bridge";
+import { isEntryEnabled, registryEntries } from "../shared/provider-registry.js";
+import { entryPolicyRefusal } from "./credential-policy.js";
+import { resolveEntryCredential } from "./credential-store.js";
+const MAX_ERROR_LENGTH = 200;
+const MIN_SECRET_LENGTH = 4;
+export function scrubSecrets(text, secrets) {
+  let out = text;
+  for (const secret of secrets) {
+    if (!secret || secret.length < MIN_SECRET_LENGTH) continue;
+    const forms = /* @__PURE__ */ new Set([
+      secret,
+      encodeURIComponent(secret),
+      Buffer.from(secret, "utf8").toString("base64")
+    ]);
+    for (const form of forms) out = out.split(form).join("***");
+  }
+  return out.length > MAX_ERROR_LENGTH ? `${out.slice(0, MAX_ERROR_LENGTH)}\u2026` : out;
+}
+export async function discoverProviderModels(providerId, registry, options) {
+  const match = registryEntries(registry).find(([id]) => id === providerId);
+  if (!match)
+    return { status: "error", providerId, error: `'${providerId}' is not in this registry` };
+  const entry = match[1];
+  if (entry.kind !== "llm") {
+    return { status: "unsupported", providerId, reason: "only llm entries list models" };
+  }
+  if (!isEntryEnabled(entry)) return { status: "error", providerId, error: "entry is disabled" };
+  const refusal = options.policy ? entryPolicyRefusal(entry, options.policy) : void 0;
+  if (refusal) return { status: "error", providerId, error: refusal };
+  const credential = resolveEntryCredential(entry, {
+    env: options.env,
+    ...options.policy ? { policy: options.policy } : {},
+    ...options.key ? { key: options.key } : {},
+    ...options.path ? { path: options.path } : {}
+  });
+  const secrets = [credential.value, ...options.redact ?? []];
+  const scrub = (text) => scrubSecrets(text, secrets);
+  if (!entry.preset) {
+    return {
+      status: "unsupported",
+      providerId,
+      reason: "this entry names no catalog preset, so its models cannot be listed; enter a model id"
+    };
+  }
+  if (credential.error && !credential.value) {
+    return { status: "error", providerId, error: scrub(credential.error) };
+  }
+  const staticList = getStaticModels(entry.preset).map(({ id, name }) => ({ id, name }));
+  if (!credential.value) {
+    return staticList.length > 0 ? {
+      status: "static",
+      providerId,
+      models: staticList,
+      reason: "no credential to query the provider with"
+    } : {
+      status: "unsupported",
+      providerId,
+      reason: "no credential, and no offline catalog for this preset"
+    };
+  }
+  const baseUrl = resolveEntryBaseUrl(entry);
+  const live = await fetchProviderModels(entry.preset, credential.value, {
+    ...baseUrl ? { baseUrl } : {},
+    env: options.env
+  });
+  if (live.ok && live.models.length > 0) {
+    return {
+      status: "live",
+      providerId,
+      models: live.models.map(({ id, name }) => ({ id, name }))
+    };
+  }
+  const reason = scrub(live.error ?? "the provider returned no models");
+  return staticList.length > 0 ? { status: "static", providerId, models: staticList, reason } : { status: "error", providerId, error: reason };
+}

package/dist/runtime/server/provider-layers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reading and writing one provider-registry layer document
+ * (`providers.yml` / `providers.yaml`) as written on disk.
+ *
+ * The upstream loader validates and drops entries it dislikes; an editor must
+ * not, or rewriting a file would delete a hand-written entry. These helpers
+ * therefore read the raw `providers` map and write it back unchanged apart
+ * from the entry being edited.
+ */
+import { type AIProviderPreset } from "@skaile/workspaces/sdk/bridge";
+/**
+ * The file a write to the layer at `path` goes to: the `.yaml` spelling when
+ * only that one exists, so an edit never shadows a hand-written document.
+ */
+export declare function providerLayerDocument(path: string): string;
+/** The catalog preset `id` names, if the catalog has one. */
+export declare function catalogPreset(id: unknown): AIProviderPreset | undefined;
+/**
+ * A layer document's `providers` map exactly as written — entries the
+ * validator would reject included, so rewriting the file never drops a
+ * hand-written entry. A missing or empty file is an empty layer.
+ *
+ * @throws When the file is not YAML or not a registry document.
+ */
+export declare function readProviderLayer(file: string): Record<string, unknown>;
+/** Write a layer's `providers` map back in the shape the upstream CLI writes. */
+export declare function writeProviderLayer(file: string, providers: Record<string, unknown>): void;

package/dist/runtime/server/provider-layers.js

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "node:fs";
+import {
+  PROVIDERS_FILENAME,
+  saveProviderRegistryFile
+} from "@skaile/workspaces/core";
+import { AI_PROVIDER_PRESETS } from "@skaile/workspaces/sdk/bridge";
+import { parse as parseYaml } from "yaml";
+const PROVIDERS_FILENAME_ALIAS = "providers.yaml";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function providerLayerDocument(path) {
+  if (existsSync(path)) return path;
+  const alias = `${path.slice(0, -PROVIDERS_FILENAME.length)}${PROVIDERS_FILENAME_ALIAS}`;
+  return existsSync(alias) ? alias : path;
+}
+export function catalogPreset(id) {
+  return typeof id === "string" && Object.hasOwn(AI_PROVIDER_PRESETS, id) ? AI_PROVIDER_PRESETS[id] : void 0;
+}
+export function readProviderLayer(file) {
+  if (!existsSync(file)) return {};
+  let document;
+  try {
+    document = parseYaml(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new Error(`${file} is not valid YAML (${err.message})`);
+  }
+  if (document === null || document === void 0) return {};
+  if (!isPlainObject(document)) throw new Error(`${file} does not contain a registry document`);
+  const providers = document.providers;
+  if (providers === void 0 || providers === null) return {};
+  if (!isPlainObject(providers)) throw new Error(`${file}: 'providers' is not a map of entries`);
+  return providers;
+}
+export function writeProviderLayer(file, providers) {
+  saveProviderRegistryFile(file, { version: 1, providers });
+}

package/dist/runtime/server/provider-service.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The provider inventory a forge app shows and selects from.
+ *
+ * Every fact here comes out of the AI provider registry the session was handed:
+ * which providers exist, whether one serves chat or speech, where it points,
+ * which credential reference backs it and whether that reference resolves.
+ * forge-settings owns no provider list and no provider-type table any more — an
+ * entry's `kind` is the discriminator, and the registry is the list.
+ *
+ * What forge deliberately does not do here:
+ *
+ *   - **Endpoint probing.** "Does this endpoint accept this key" is the
+ *     runtime's `skaile providers test` / the catalog's entry probe, which
+ *     knows every surface's shape. {@link testAIProviderCredential} answers the
+ *     question forge owns: does the credential reference resolve, and where
+ *     from. That is the failure mode a settings modal must explain.
+ *   - **Live model discovery.** Model lists come from the entry's own
+ *     `model_map`/`capabilities`; harness-backed discovery is
+ *     `listModelsForHarness(harnessId, registry)` in the runtime.
+ */
+import type { AIProviderCapabilities, AIProviderCredentialKind, AIProviderKind, AIProviderRegistryView, AIProviderSurface, AIProviderVoiceParams } from "../shared/provider-registry.js";
+import { type CredentialSource, type CredentialStoreOptions } from "./credential-store.js";
+/** One registry entry, as a settings UI needs to see it. */
+export interface ProviderInfo {
+    /** Registry id — the left half of a `"<providerId>/<modelId>"` selector. */
+    id: string;
+    /** Display name: the entry's `label`, else its id. */
+    name: string;
+    /** What the entry produces. Replaces forge's old llm/stt/tts guesswork. */
+    kind: AIProviderKind;
+    /** Whether the entry's credential resolved to a value in this process. */
+    configured: boolean;
+    /** Which reference form answered — `ambient` means a cloud SDK chain signs. */
+    source: CredentialSource;
+    /** Why the credential did not resolve. Secret-free, safe to render. */
+    error?: string;
+    /** The entry's `credential.ref`. A reference, never a secret. */
+    credentialRef?: string;
+    /** How the credential is presented on the wire. */
+    credentialKind?: AIProviderCredentialKind;
+    /**
+     * Whether the entry's reference is an `env:` one. The variable is shared by
+     * every user of the server, so a settings UI names it rather than pretending
+     * the value behind it is the user's to change.
+     */
+    hasEnvKey: boolean;
+    /** Name of that environment variable, when {@link hasEnvKey}. */
+    envKeyName?: string;
+    /** Endpoint the entry pins, when it pins one. */
+    baseUrl?: string;
+    /** Catalog preset the entry inherits from, when it names one. */
+    preset?: string;
+    /** Wire protocol of an `llm`/`embed` entry (its own or its preset's). */
+    surface?: AIProviderSurface;
+    /** The entry's `enabled` flag; `false` only in a listing with `includeDisabled`. */
+    enabled: boolean;
+    /**
+     * Voice parameters a `kind: stt|tts` entry declares — Deepgram
+     * `{model, language}`, ElevenLabs `{voice_id, output_format}`. A settings UI
+     * shows these as the defaults a per-request override replaces; `llm`/`embed`
+     * entries never carry them.
+     */
+    params?: AIProviderVoiceParams;
+    /** Frozen by the control plane: a lower layer cannot change or disable it. */
+    locked: boolean;
+}
+/** One selectable model of one provider. */
+export interface ModelInfo {
+    /** The selector to store in `settings.model`: `"<providerId>/<modelId>"`. */
+    id: string;
+    /** Display name — the logical model id. */
+    name: string;
+    /** Registry id of the entry serving the model. */
+    providerId: string;
+    /** Logical id: the `model_map` key. */
+    modelId: string;
+    /** Provider-side id the logical id maps to. */
+    providerModelId: string;
+    /** Capability facts the entry declares for this model, when any. */
+    capabilities?: AIProviderCapabilities;
+}
+/** Result of resolving one entry's credential on demand. */
+export interface ProviderTestResult {
+    /** Whether the credential resolved to a usable value. */
+    ok: boolean;
+    /** Registry id that was tested. */
+    provider: string;
+    /** Which reference form answered. */
+    source: CredentialSource;
+    /** Why it did not resolve. Secret-free. */
+    error?: string;
+}
+/** What {@link listAIProviders} resolves credentials against, and which entries it lists. */
+export interface ListAIProvidersOptions extends CredentialStoreOptions {
+    /** List `enabled: false` entries too (a registry editor's view). Default `false`. */
+    includeDisabled?: boolean;
+}
+/**
+ * Describe every enabled registry entry, in registry order — every entry with
+ * `includeDisabled`.
+ *
+ * Unconfigured entries are included: an entry whose `env:` variable is missing
+ * is exactly what the user has to see and fix, and hiding it (the pre-5.0.0
+ * behaviour, which filtered on "has a key") turned a typo into an empty list.
+ */
+export declare function listAIProviders(registry: AIProviderRegistryView, options?: ListAIProvidersOptions): ProviderInfo[];
+/**
+ * List the models the registry declares, as `"<providerId>/<modelId>"`
+ * selectors.
+ *
+ * Sourced from each `llm`/`embed` entry's `model_map` (plus any id that only
+ * appears in `capabilities`) — the same two tables the runtime's model-reference
+ * resolver reads, so a selector built from this list always resolves.
+ *
+ * @param providerId - Restrict to one entry; omit for every enabled entry.
+ */
+export declare function listAIProviderModels(registry: AIProviderRegistryView, providerId?: string): ModelInfo[];
+/**
+ * Resolve one entry's credential and report the outcome.
+ *
+ * This is the check behind a settings modal's per-provider indicator: it proves
+ * the reference points at something this server can read, and names the layer
+ * that owns it when it does not (`cmd:` in the spawned runtime, `platform:` in
+ * the control plane).
+ */
+export declare function testAIProviderCredential(providerId: string, registry: AIProviderRegistryView, options?: CredentialStoreOptions): ProviderTestResult;

package/dist/runtime/server/provider-service.js

@@ -0,0 +1,87 @@
+import {
+  entriesOfKind,
+  isEntryEnabled,
+  isVoiceEntry,
+  parseCredentialRef,
+  registryEntries
+} from "../shared/provider-registry.js";
+import {
+  resolveEntryCredential
+} from "./credential-store.js";
+export function listAIProviders(registry, options = {}) {
+  const providers = [];
+  for (const [id, entry] of registryEntries(registry)) {
+    const enabled = isEntryEnabled(entry);
+    if (!enabled && !options.includeDisabled) continue;
+    const resolved = resolveEntryCredential(entry, options);
+    const ref = entry.credential?.ref;
+    const parsed = ref ? parseCredentialRef(ref) : void 0;
+    providers.push({
+      id,
+      name: entry.label?.trim() || id,
+      kind: entry.kind,
+      // No error means usable: a value resolved, none is needed (`kind: none`),
+      // or an ambient cloud chain signs the request.
+      configured: resolved.error === void 0,
+      source: resolved.source,
+      ...resolved.error ? { error: resolved.error } : {},
+      ...ref ? { credentialRef: ref } : {},
+      ...entry.credential ? { credentialKind: entry.credential.kind } : {},
+      hasEnvKey: parsed?.form === "env",
+      ...parsed?.form === "env" ? { envKeyName: parsed.name } : {},
+      ...entry.base_url ? { baseUrl: entry.base_url } : {},
+      ...entry.preset ? { preset: entry.preset } : {},
+      ...!isVoiceEntry(entry) && entry.surface ? { surface: entry.surface } : {},
+      enabled,
+      ...isVoiceEntry(entry) && entry.params ? { params: entry.params } : {},
+      locked: entry.locked === true
+    });
+  }
+  return providers;
+}
+export function listAIProviderModels(registry, providerId) {
+  const models = [];
+  for (const kind of ["llm", "embed"]) {
+    for (const [id, entry] of entriesOfKind(registry, kind)) {
+      if (providerId && id !== providerId) continue;
+      const logicalIds = /* @__PURE__ */ new Set([
+        ...Object.keys(entry.model_map ?? {}),
+        ...Object.keys(entry.capabilities ?? {})
+      ]);
+      for (const modelId of logicalIds) {
+        const capabilities = entry.capabilities?.[modelId];
+        models.push({
+          id: `${id}/${modelId}`,
+          name: modelId,
+          providerId: id,
+          modelId,
+          providerModelId: entry.model_map?.[modelId] ?? modelId,
+          ...capabilities ? { capabilities } : {}
+        });
+      }
+    }
+  }
+  return models;
+}
+export function testAIProviderCredential(providerId, registry, options = {}) {
+  const match = registryEntries(registry).find(([id]) => id === providerId);
+  if (!match) {
+    return {
+      ok: false,
+      provider: providerId,
+      source: "none",
+      error: `'${providerId}' is not an entry in this registry`
+    };
+  }
+  const [, entry] = match;
+  if (!isEntryEnabled(entry)) {
+    return { ok: false, provider: providerId, source: "none", error: "entry is disabled" };
+  }
+  const resolved = resolveEntryCredential(entry, options);
+  return {
+    ok: resolved.error === void 0,
+    provider: providerId,
+    source: resolved.source,
+    ...resolved.error ? { error: resolved.error } : {}
+  };
+}

package/dist/runtime/server/provider-settings.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Where a forge app's settings meet the AI provider registry.
+ *
+ * Two jobs:
+ *
+ *   1. **Migration.** A `settings.json` written before the 5.0.0 registry migration holds
+ *      `provider` + a free-text `model`, and an `apiKeys` map of secrets. On
+ *      first load the pair collapses into one `"<providerId>/<modelId>"`
+ *      selector, and the `apiKeys` map is dropped with a warning — a plaintext
+ *      key is never auto-written anywhere; the user moves it into `.env`.
+ *   2. **Voice selection.** `sttProvider`/`ttsProvider` are registry ids of
+ *      `kind: stt|tts` entries; the endpoint and the voice parameters live on
+ *      the entry, and `sttLanguage`/`ttsVoice` are per-request overrides of two
+ *      of those parameters. Resolving all of that used to be three apps'
+ *      worth of hardcoded endpoints and voice ids.
+ */
+import type { AIProviderVoiceEntry, AIProviderVoiceKind, AIProviderVoiceParams, AIProviderRegistryView } from "../shared/provider-registry.js";
+import type { SkaileSettings } from "../shared/settings-types.js";
+/** What {@link migrateLegacyProviderSettings} did to one settings file. */
+export interface LegacySettingsMigration {
+    /** The file that was inspected. */
+    path: string;
+    /** Whether the file was rewritten. */
+    changed: boolean;
+    /** The selector `provider` + `model` collapsed into, when that happened. */
+    model?: string;
+    /** Everything dropped or left untouched, and why. Secret-free. */
+    warnings: string[];
+}
+/**
+ * Migrate one legacy `settings.json` in place. Idempotent: a file with no
+ * legacy `provider` and no `apiKeys` is left byte-identical.
+ *
+ * An `apiKeys` map is removed from the file and never stored anywhere else:
+ * the registry holds references only, and a plaintext key has no safe
+ * automatic destination. Each non-empty entry is reported through `warnings`
+ * (without the key) so the user can move it into `.env`.
+ *
+ * @param settingsPath - Absolute path to a `settings.json`.
+ */
+export declare function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration;
+/** Settings fields that name a voice entry and override its parameters. */
+export type VoiceSettings = Pick<SkaileSettings, "sttProvider" | "ttsProvider" | "sttLanguage" | "ttsVoice">;
+/** The `kind: stt|tts` entry a request runs against, with its parameters resolved. */
+export interface VoiceProviderSelection {
+    /** Registry id of the entry. */
+    providerId: string;
+    entry: AIProviderVoiceEntry;
+    /** Endpoint from the entry; absent when the entry inherits its preset's default. */
+    baseUrl?: string;
+    /**
+     * The entry's `params` with overrides applied — Deepgram `{model, language}`,
+     * ElevenLabs `{voice_id, output_format}`. This is the only place a forge app
+     * should read voice defaults from.
+     */
+    params: AIProviderVoiceParams;
+    /** True when settings named no usable entry and registry order decided. */
+    fallback: boolean;
+    /** Non-fatal notes, e.g. settings naming an entry the registry does not have. */
+    warnings: string[];
+}
+/**
+ * Resolve which registry entry serves speech-to-text or text-to-speech.
+ *
+ * Selection is `settings.sttProvider`/`settings.ttsProvider`, falling back to
+ * the first enabled entry of that kind in registry order when the setting is
+ * absent or names an entry that is gone — a missing setting must not silence an
+ * app that has a perfectly good entry configured.
+ *
+ * Parameter precedence, lowest first: the entry's `params`, then the settings
+ * overrides (`sttLanguage` → `language`, `ttsVoice` → `voice_id`), then
+ * `overrides` from the request. The per-request override is the contract
+ * forge-concept already honoured and the other apps silently dropped.
+ *
+ * @returns The selection, or `undefined` when the registry has no enabled entry
+ *          of that kind.
+ */
+export declare function resolveVoiceProvider(registry: AIProviderRegistryView, kind: AIProviderVoiceKind, settings?: VoiceSettings, overrides?: AIProviderVoiceParams): VoiceProviderSelection | undefined;

package/dist/runtime/server/provider-settings.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  entriesOfKind,
+  selectVoiceEntryId,
+  VOICE_OVERRIDE_PARAM
+} from "../shared/provider-registry.js";
+export function migrateLegacyProviderSettings(settingsPath) {
+  const result = {
+    path: settingsPath,
+    changed: false,
+    warnings: []
+  };
+  if (!existsSync(settingsPath)) return result;
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch (err) {
+    result.warnings.push(`${settingsPath} is not valid JSON (${err.message})`);
+    return result;
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    result.warnings.push(`${settingsPath} does not contain a settings object`);
+    return result;
+  }
+  const legacyProvider = typeof settings.provider === "string" ? settings.provider.trim() : "";
+  if (legacyProvider) {
+    const model = typeof settings.model === "string" ? settings.model.trim() : "";
+    if (model && !model.includes("/")) {
+      settings.model = `${legacyProvider}/${model}`;
+      result.model = settings.model;
+    } else if (!model) {
+      result.warnings.push(
+        `provider '${legacyProvider}' had no model to namespace \u2014 the session now resolves its model through the registry's own order`
+      );
+    }
+    delete settings.provider;
+    result.changed = true;
+  }
+  if ("apiKeys" in settings) {
+    const apiKeys = settings.apiKeys;
+    const hasSecret = typeof apiKeys === "object" && apiKeys !== null && Object.values(apiKeys).some((value) => typeof value === "string" && value !== "");
+    if (hasSecret) {
+      result.warnings.push(
+        "apiKeys found in settings: move each key into .env and reference it from providers.yml (skaile providers add)"
+      );
+    }
+    delete settings.apiKeys;
+    result.changed = true;
+  }
+  if (result.changed) {
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
+`, "utf8");
+  }
+  return result;
+}
+export function resolveVoiceProvider(registry, kind, settings = {}, overrides = {}) {
+  const candidates = entriesOfKind(registry, kind);
+  if (candidates.length === 0) return void 0;
+  const warnings = [];
+  const wanted = (kind === "stt" ? settings.sttProvider : settings.ttsProvider)?.trim();
+  const ids = candidates.map(([id]) => id);
+  const providerId = selectVoiceEntryId(ids, wanted);
+  const entry = candidates[ids.indexOf(providerId)][1];
+  if (wanted && wanted !== providerId) {
+    warnings.push(
+      `settings name '${wanted}' for ${kind}, which is not an enabled ${kind} entry \u2014 using '${providerId}' instead`
+    );
+  }
+  const fallback = wanted !== providerId;
+  const settingsOverride = {};
+  const override = (kind === "stt" ? settings.sttLanguage : settings.ttsVoice)?.trim();
+  if (override) settingsOverride[VOICE_OVERRIDE_PARAM[kind]] = override;
+  return {
+    providerId,
+    entry,
+    ...entry.base_url ? { baseUrl: entry.base_url } : {},
+    params: { ...entry.params, ...settingsOverride, ...overrides },
+    fallback,
+    warnings
+  };
+}

package/dist/runtime/server/provider-write.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Editing the provider registry's on-disk layers over HTTP: the instance
+ * layer (admins) and a workspace's `<root>/.skaile/providers.yml` (write
+ * access, unless the admin locked providers).
+ *
+ * A layer file holds references, never secrets: a body that carries a key
+ * value is refused before anything else, and `credential.ref` must be one of
+ * the four reference forms. Every write is gated on the registry it would
+ * produce — the scope's layers merged over the catalog presets the entries
+ * name, as the spawned child merges them — so an entry the child would drop is
+ * refused with the upstream diagnostics instead of being written.
+ *
+ * An entry a lower document defines can be **patched** from a higher scope:
+ * a body holding only {@link PATCH_KEYS} is stored under that id in the
+ * scope's own document, where the registry merge applies it field by field
+ * over the inherited entry. Removing it again (`removeProviderEntry`) is the
+ * patch's reset.
+ *
+ * Writes never touch live sessions: a running chat keeps its endpoint until
+ * its model or harness changes.
+ *
+ * Auth stays in the app: it builds the {@link ProviderWriteScope} (paths, env,
+ * lock state), asks {@link providerScopeWritable}, and answers 403 itself.
+ */
+import { type AIProviderPreset } from "@skaile/workspaces/sdk/bridge";
+import type { AIProviderRegistry } from "../shared/provider-registry.js";
+import { type CredentialPolicy } from "./credential-policy.js";
+/**
+ * A refused provider write. Framework-free: a Nitro / h3 host answers a thrown
+ * error carrying `statusCode`, `statusMessage` and `data` with exactly that
+ * status, message and body, the same as one made by `createError`.
+ */
+export declare class ProviderWriteError extends Error {
+    readonly statusCode: number;
+    readonly statusMessage: string;
+    readonly data?: unknown;
+    constructor(input: {
+        statusCode: number;
+        statusMessage: string;
+        data?: unknown;
+    });
+}
+/** The refusal for a body that carries a secret instead of a reference. */
+export declare const PROVIDER_SECRET_REFUSAL = "Secrets go into the scope's .env; reference them as env:NAME";
+/** Entry fields a higher scope may set on an entry a lower document defines. */
+export declare const PATCH_KEYS: readonly ["credential", "enabled"];
+/** One registry layer file a write goes to, and the layers merged beneath it. */
+export interface ProviderWriteScope {
+    /** Which registry the caller edits. */
+    name: "instance" | "workspace";
+    /** The scope's own document (its `.yaml` spelling when only that one exists). */
+    file: string;
+    /** Documents merged beneath it, lowest first; empty for the lowest layer. */
+    below: string[];
+    /** The scope's effective environment, as `env:` credential references resolve against it. */
+    env: Record<string, string | undefined>;
+    /** The control plane's provider lock is in force: only an admin may write. */
+    lock: boolean;
+    /**
+     * The host's credential policy. A write whose resulting entry names a
+     * reference or environment variable the policy refuses is a 400 and nothing
+     * is written. Absent: no restriction.
+     */
+    policy?: CredentialPolicy;
+}
+/**
+ * Whether the caller may write the scope's document: an admin always; anyone
+ * else only to a workspace document while providers are not locked.
+ */
+export declare function providerScopeWritable(scope: ProviderWriteScope, caller: {
+    isAdmin: boolean;
+}): boolean;
+/**
+ * Upsert entry `id` in the scope's document.
+ *
+ * - **Own entry** — the body sets the editable fields (`BODY_KEYS`) — one it
+ *   omits is removed — and optionally `kind`; fields it does not set (`kind`,
+ *   `transport`, `params`, …) keep their written value.
+ * - **Patch** — when a lower document defines `id` and the body holds only
+ *   {@link PATCH_KEYS}, the body is merged into the scope's stored entry for
+ *   `id` (created when absent), leaving every other stored field alone.
+ *
+ * The file and its directory are created when absent; other entries are kept
+ * as written.
+ *
+ * 400: invalid id, secret-bearing or malformed body, a body for an inherited
+ * entry that is neither a patch nor over an own full entry, or any error
+ * diagnostic for the entry (as `data.diagnostics`; nothing is written). 403:
+ * the entry is `locked: true` in some document. 409: the document on disk is
+ * not a registry.
+ */
+export declare function upsertProviderEntry(scope: ProviderWriteScope, id: string, body: unknown): {
+    id: string;
+    entry: Record<string, unknown>;
+};
+/**
+ * Remove entry `id` from the scope's document; 404 when that document does
+ * not define it. On a patched entry that deletes the patch and the inherited
+ * entry shows through again.
+ */
+export declare function removeProviderEntry(scope: ProviderWriteScope, id: string): {
+    id: string;
+};
+/** A catalog preset as the settings modal lists it. */
+export interface ProviderPresetSummary {
+    id: string;
+    label: string;
+    kind: AIProviderPreset["kind"];
+    surface?: AIProviderPreset["surface"];
+    base_url?: string;
+    base_url_env?: string;
+    credential: {
+        kind: AIProviderPreset["credential"]["kind"];
+        env?: string;
+    };
+}
+/** Catalog presets (all of them by default), in catalog order. */
+export declare function providerPresetSummaries(presets?: AIProviderPreset[]): ProviderPresetSummary[];
+/**
+ * Presets a scope could configure right now: their `credential.env` is set
+ * in `env`, and no entry of `registry` is the preset's id or names it as its
+ * `preset`.
+ *
+ * @param env - The scope's layered environment.
+ * @param registry - The scope's merged registry.
+ */
+export declare function detectedProviderPresets(env: Record<string, string | undefined>, registry: AIProviderRegistry): ProviderPresetSummary[];
+/** Which registry document holds a provider entry the scope lists. */
+export type ProviderLayerName = ProviderWriteScope["name"];
+/**
+ * The defining document's values for the `PUT`-editable fields a settings UI
+ * edit dialog does not show. A `PUT` removes every editable field it omits,
+ * so an edit sends these back unchanged instead of dropping them.
+ */
+export interface ProviderLayerFields {
+    label?: unknown;
+    headers?: unknown;
+    model_map?: unknown;
+    enabled?: unknown;
+}
+/**
+ * Tag each provider view of a scope with every registry document that holds
+ * its id — `layers`, lowest first: `"instance"` for each lower document, then
+ * the scope's own name when its own document holds it. An id no document
+ * holds (not expected) is attributed to the lowest layer of the scope.
+ * `layerFields` are the {@link ProviderLayerFields} of the scope's own entry,
+ * or of the lowest document holding the id when the scope has none.
+ */
+export declare function withProviderLayers<T extends {
+    id: string;
+}>(views: T[], scope: ProviderWriteScope): Array<T & {
+    layers: ProviderLayerName[];
+    layerFields: ProviderLayerFields;
+}>;